diff --git a/Makefile b/Makefile
index dd0634b7..2c661f9a 100644
--- a/Makefile
+++ b/Makefile
@@ -1,7 +1,7 @@
 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 layers/highway_name/README.md layers/poi/README.md layers/place/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 layers/place/README.md layers/waterway/README.md layers/water_name/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
@@ -27,9 +27,15 @@ layers/railway/README.md:
 layers/boundary/README.md:
 	generate-doc layers/boundary/boundary.yaml --diagram layers/boundary/mapping > layers/boundary/README.md
 
+layers/water_name/README.md:
+	generate-doc layers/water_name/water_name.yaml > layers/water_name/README.md
+
 layers/water/README.md:
 	generate-doc layers/water/water.yaml --diagram layers/water/mapping > layers/water/README.md
 
+layers/waterway/README.md:
+	generate-doc layers/waterway/waterway.yaml --diagram layers/waterway/mapping > layers/waterway/README.md
+
 layers/building/README.md:
 	generate-doc layers/building/building.yaml > layers/building/README.md
 
diff --git a/layers/water_name/README.md b/layers/water_name/README.md
new file mode 100644
index 00000000..a87f4eb9
--- /dev/null
+++ b/layers/water_name/README.md
@@ -0,0 +1,14 @@
+# water_name
+
+Lake center lines for labelling lake bodies.
+This is based of the [osm-lakelines](https://github.com/lukasmartinelli/osm-lakelines) project
+which derives nice centerlines from OSM water bodies. Only the most important lakes contain labels.
+
+## Fields
+
+- **name_en**: The english `name:en` value if available.
+- **name**: The OSM [`name`](http://wiki.openstreetmap.org/wiki/Key:name) value of the water body.
+- **class**: At the moment only `lake` since no ocean parts are labelled. *Reserved for future use*.
+
+
+
diff --git a/layers/water_name/water_name.yaml b/layers/water_name/water_name.yaml
index 8080b446..33d6b006 100644
--- a/layers/water_name/water_name.yaml
+++ b/layers/water_name/water_name.yaml
@@ -1,11 +1,16 @@
 layer:
   id: "water_name"
   description: |
-      OSM lakelines.
+      Lake center lines for labelling lake bodies.
+      This is based of the [osm-lakelines](https://github.com/lukasmartinelli/osm-lakelines) project
+      which derives nice centerlines from OSM water bodies. Only the most important lakes contain labels.
+  fields:
+    name: The OSM [`name`](http://wiki.openstreetmap.org/wiki/Key:name) value of the water body.
+    name_en: The english `name:en` value if available.
+    class: |
+        At the moment only `lake` since no ocean parts are labelled. *Reserved for future use*.
   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
   datasource:
     geometry_field: geometry
     srid: 900913
diff --git a/layers/waterway/README.md b/layers/waterway/README.md
new file mode 100644
index 00000000..48983945
--- /dev/null
+++ b/layers/waterway/README.md
@@ -0,0 +1,20 @@
+# waterway
+
+Rivers based of OpenStreetMap [waterways](http://wiki.openstreetmap.org/wiki/Waterways) for *z8* to *z14*
+and Natural Earth rivers and lake centerlines from *z3* to *z7*.
+Too short linestrings are filtered out for some zoom levels. Waterways do no not have a `subclass`.
+
+## Fields
+
+- **class**: The original value of the [`waterway`](http://wiki.openstreetmap.org/wiki/Key:waterway) tag.
+Can be one of [`stream`](http://wiki.openstreetmap.org/wiki/Tag:waterway%3Dstream),
+[`river`](http://wiki.openstreetmap.org/wiki/Tag:waterway%3Driver),
+[`canal`](http://wiki.openstreetmap.org/wiki/Tag:waterway%3Dcanal),
+[`drain`](http://wiki.openstreetmap.org/wiki/Tag:waterway%3Ddrain),
+[`ditch`](http://wiki.openstreetmap.org/wiki/Tag:waterway%3Dditch)`.
+
+## Mapping
+
+![](mapping.png)
+
+
diff --git a/layers/waterway/mapping.png b/layers/waterway/mapping.png
new file mode 100644
index 00000000..51a4f6e7
Binary files /dev/null and b/layers/waterway/mapping.png differ
diff --git a/layers/waterway/waterway.yaml b/layers/waterway/waterway.yaml
index 10c84219..e8223311 100644
--- a/layers/waterway/waterway.yaml
+++ b/layers/waterway/waterway.yaml
@@ -1,8 +1,18 @@
 layer:
   id: "waterway"
   description: |
-      OpenStreetMap waterways.
+      Rivers based of OpenStreetMap [waterways](http://wiki.openstreetmap.org/wiki/Waterways) for *z8* to *z14*
+      and Natural Earth rivers and lake centerlines from *z3* to *z7*.
+      Too short linestrings are filtered out for some zoom levels. Waterways do no not have a `subclass`.
   buffer_size: 4
+  fields:
+    class: |
+        The original value of the [`waterway`](http://wiki.openstreetmap.org/wiki/Key:waterway) tag.
+        Can be one of [`stream`](http://wiki.openstreetmap.org/wiki/Tag:waterway%3Dstream),
+        [`river`](http://wiki.openstreetmap.org/wiki/Tag:waterway%3Driver),
+        [`canal`](http://wiki.openstreetmap.org/wiki/Tag:waterway%3Dcanal),
+        [`drain`](http://wiki.openstreetmap.org/wiki/Tag:waterway%3Ddrain),
+        [`ditch`](http://wiki.openstreetmap.org/wiki/Tag:waterway%3Dditch)`.
   datasource:
     geometry_field: geometry
     query: (SELECT geometry, class FROM layer_waterway(!bbox!, z(!scale_denominator!))) AS t