diff --git a/README.md b/README.md
index 4475ef4..07a6bd0 100644
--- a/README.md
+++ b/README.md
@@ -4,8 +4,46 @@
This repository provides a simple script to generate TopoJSON files from the [Spanish National Geographic Institute’s](http://www.ign.es/ign/main/index.do) [National Reference Geographic Equipment](http://centrodedescargas.cnig.es/CentroDescargas/equipamiento.do?method=mostrarEquipamiento) vector data.
+## Getting started
+
+Clone or download the repository, start a terminal and run `npm install` in the folder. This command will download the shapefiles from the IGN, join them and convert them to [TopoJSON](https://github.com/topojson/topojson).
+
+If you need to make further adjustments (simplification, quantization) you can adjust the `package.json` config and run `npm install` again.
+
+## File Reference
+
+#es/municipalities.json · [Download](https://unpkg.com/es-atlas/es/municipalities.json)
+
+A TopoJSON which contains four objects: _municipalities_, _provinces_, _autonomous regions_ and _border_. Every city, province and region has its corresponding [National Statistics Institute](http://www.ine.es/en/welcome.shtml) identifier and name, so it's easy to get started.
+
+# _es_.objects.municipalities
+
+
+
+# _es_.objects.provinces
+
+
+
+# _es_.objects.autonomous_regions
+
+
+
+# _es_.objects.border
+
+
+
+#es/provinces.json · [Download](https://unpkg.com/es-atlas/es/provinces.json)
+
+This file provides provinces and autonomous regions, to keep a smaller footprint on less detailed maps.
+
+#es/autonomous_regions.json · [Download](https://unpkg.com/es-atlas/es/autonomous_regions.json)
+
+This file only provides autonomous regions, to keep a smaller footprint on less detailed maps.
+
## Usage
+To render the map I recommend using the `geoConicConformalSpain` projection created by Roger Veciana, included in [d3-composite-projections](https://github.com/rveciana/d3-composite-projections). This projection ensures that the Canary Islands are painted closer to the mainland and [include a border](https://bl.ocks.org/rveciana/d635afded8c4eae36ecf61a15bdf0a98) to mark the projection zone.
+
You can see an interactive example in this [Observable notebook](https://observablehq.com/@martgnz/mapa-de-espana-con-topojson-y-es-atlas).
For the browser with [d3-geo](https://github.com/d3/d3-geo) and SVG:
@@ -13,7 +51,7 @@ For the browser with [d3-geo](https://github.com/d3/d3-geo) and SVG:
```html
-
+
+
+# _es_.objects.provinces
+
+
+
+# _es_.objects.autonomous_regions
+
+
+
+# _es_.objects.border
+
+
+
+# es/provinces.json · [Download](https://unpkg.com/es-atlas/es/provinces.json)
+
+This file provides provinces and autonomous regions, to keep a smaller footprint on less detailed maps.
+
+# es/autonomous_regions.json · [Download](https://unpkg.com/es-atlas/es/autonomous_regions.json)
+
+This file only provides autonomous regions, to keep a smaller footprint on less detailed maps.
+
## Usage
+To render the map I recommend using the `geoConicConformalSpain` projection created by Roger Veciana, included in [d3-composite-projections](https://github.com/rveciana/d3-composite-projections). This projection ensures that the Canary Islands are painted closer to the mainland and [include a border](https://bl.ocks.org/rveciana/d635afded8c4eae36ecf61a15bdf0a98) to mark the projection zone.
+
You can see an interactive example in this [Observable notebook](https://observablehq.com/@martgnz/mapa-de-espana-con-topojson-y-es-atlas).
For the browser with [d3-geo](https://github.com/d3/d3-geo) and SVG:
@@ -13,7 +51,7 @@ For the browser with [d3-geo](https://github.com/d3/d3-geo) and SVG:
```html
-
+