diff --git a/Makefile b/Makefile
index b9f4cd2..aa4765c 100644
--- a/Makefile
+++ b/Makefile
@@ -1,7 +1,8 @@
 all: build/openmaptiles.tm2source/data.yml build/mapping.yaml build/tileset.sql
 
 .PHONY: docs
-docs: layers/railway/README.md layers/boundary/README.md layers/water/README.md layers/building/README.md layers/highway/README.md
+docs: layers/railway/README.md layers/boundary/README.md layers/water/README.md layers/building/README.md layers/highway/README.md layers/highway_name/README.md layers/poi/README.md
+
 
 build/openmaptiles.tm2source/data.yml:
 	mkdir -p build/openmaptiles.tm2source && generate-tm2source openmaptiles.yaml --host="postgres" --port=5432 --database="openmaptiles" --user="openmaptiles" --password="openmaptiles" > build/openmaptiles.tm2source/data.yml
@@ -12,9 +13,15 @@ build/mapping.yaml:
 build/tileset.sql:
 	mkdir -p build && generate-sql openmaptiles.yaml > build/tileset.sql
 
+layers/poi/README.md:
+	generate-doc layers/poi/poi.yaml --diagram layers/poi/mapping > layers/poi/README.md
+
 layers/highway/README.md:
 	generate-doc layers/highway/highway.yaml --diagram layers/highway/mapping > layers/highway/README.md
 
+layers/highway_name/README.md:
+	generate-doc layers/highway_name/highway_name.yaml > layers/highway_name/README.md
+
 layers/railway/README.md:
 	generate-doc layers/railway/railway.yaml --diagram layers/railway/mapping > layers/railway/README.md
 
diff --git a/layers/poi/README.md b/layers/poi/README.md
new file mode 100644
index 0000000..cf6103e
--- /dev/null
+++ b/layers/poi/README.md
@@ -0,0 +1,31 @@
+# poi
+
+[Points of interests](http://wiki.openstreetmap.org/wiki/Points_of_interest) containing
+a of a variety of OpenStreetMap tags. Mostly contains amenities, sport, shop and tourist POIs.
+
+## Fields
+
+- **class**: More general classes of POIs. If there is no more general `class` for the `subclass`
+this field will contain the same value as `subclass`.
+But for example for schools you only need to style the class `school` to filter the subclasses `school`
+and `kindergarten`. Or use the class `shop` to style all shops.
+- **gridrank**: The POIs are ranked ascending according to their importance within a grid. The `gridrank` value shows the
+local relative importance of a POI within it's cell in the grid. This can be used to reduce label density at z14.
+Since all POIs already need to be contained at `z14` you can use `less than gridrank=10` epxression to limit
+POIs. At some point like z17 you can show all POIs.
+- **name_en**: The english `name:en` value if available.
+- **subclass**: Original value of either the
+[`amenity`](http://wiki.openstreetmap.org/wiki/Key:amenity),
+[`leisure`](http://wiki.openstreetmap.org/wiki/Key:leisure),
+[`landuse`](http://wiki.openstreetmap.org/wiki/Key:landuse),
+[`sport`](http://wiki.openstreetmap.org/wiki/Key:sport),
+[`tourism`](http://wiki.openstreetmap.org/wiki/Key:tourism)
+or [`shop`](http://wiki.openstreetmap.org/wiki/Key:shop)
+tag.  Use this to do more precise styling.
+- **name**: The OSM [`name`](http://wiki.openstreetmap.org/wiki/Key:name) value of the POI.
+
+## Mapping
+
+![](mapping.png)
+
+
diff --git a/layers/poi/mapping.png b/layers/poi/mapping.png
new file mode 100644
index 0000000..7b85381
Binary files /dev/null and b/layers/poi/mapping.png differ
diff --git a/layers/poi/poi.yaml b/layers/poi/poi.yaml
index aab9e50..0cfdb00 100644
--- a/layers/poi/poi.yaml
+++ b/layers/poi/poi.yaml
@@ -1,11 +1,32 @@
 layer:
   id: "poi"
   description: |
-      POIs.
+      [Points of interests](http://wiki.openstreetmap.org/wiki/Points_of_interest) containing
+      a of a variety of OpenStreetMap tags. Mostly contains amenities, sport, shop and tourist POIs.
   buffer_size: 8
   srs: +proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over
   fields:
-    class: String
+    name: The OSM [`name`](http://wiki.openstreetmap.org/wiki/Key:name) value of the POI.
+    name_en: The english `name:en` value if available.
+    class: |
+        More general classes of POIs. If there is no more general `class` for the `subclass`
+        this field will contain the same value as `subclass`.
+        But for example for schools you only need to style the class `school` to filter the subclasses `school`
+        and `kindergarten`. Or use the class `shop` to style all shops.
+    subclass: |
+        Original value of either the
+        [`amenity`](http://wiki.openstreetmap.org/wiki/Key:amenity),
+        [`leisure`](http://wiki.openstreetmap.org/wiki/Key:leisure),
+        [`landuse`](http://wiki.openstreetmap.org/wiki/Key:landuse),
+        [`sport`](http://wiki.openstreetmap.org/wiki/Key:sport),
+        [`tourism`](http://wiki.openstreetmap.org/wiki/Key:tourism)
+        or [`shop`](http://wiki.openstreetmap.org/wiki/Key:shop)
+        tag.  Use this to do more precise styling.
+    gridrank: |
+        The POIs are ranked ascending according to their importance within a grid. The `gridrank` value shows the
+        local relative importance of a POI within it's cell in the grid. This can be used to reduce label density at z14.
+        Since all POIs already need to be contained at `z14` you can use `less than gridrank=10` epxression to limit
+        POIs. At some point like z17 you can show all POIs.
   datasource:
     geometry_field: geometry
     srid: 900913