diff --git a/Makefile b/Makefile
index 3c9d841..804babb 100644
--- a/Makefile
+++ b/Makefile
@@ -1,4 +1,4 @@
-all: build/openmaptiles.tm2source/data.yml build/mapping.yaml build/tileset.sql layers/railway/README.md layers/boundary/README.md
+all: build/openmaptiles.tm2source/data.yml build/mapping.yaml build/tileset.sql layers/railway/README.md layers/boundary/README.md layers/water/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
@@ -15,5 +15,8 @@ layers/railway/README.md:
 layers/boundary/README.md:
 	generate-doc layers/boundary/boundary.yaml --diagram layers/boundary/mapping > layers/boundary/README.md
 
+layers/water/README.md:
+	generate-doc layers/water/water.yaml --diagram layers/water/mapping > layers/water/README.md
+
 clean:
 	rm -f build/openmaptiles.tm2source/data.yml && rm -f build/mapping.yaml && rm -f build/tileset.sql && rm -f layers/**/README.md&& rm -f layers/**/*.png
diff --git a/layers/water/README.md b/layers/water/README.md
new file mode 100644
index 0000000..1152e62
--- /dev/null
+++ b/layers/water/README.md
@@ -0,0 +1,18 @@
+# water
+
+Water polygons representing oceans and lakes. Covered watered areas are excluded (`covered=yes`).
+Until z6 all water originates from Natural Earth. To get a more correct display of the south pole you should also
+style the covering ice shelves over the water.
+Water from OpenStreetMap after z7 is split into many smaller polygons to improve rendering performance.
+This however can lead to less rendering options in clients since these boundaries show up. So you might not be
+able to use border styling for ocean water features.
+
+## Fields
+
+- **class**: Either `ocean`, `lake` or `river`.
+
+## Mapping
+
+![](mapping.png)
+
+
diff --git a/layers/water/mapping.png b/layers/water/mapping.png
new file mode 100644
index 0000000..f0f09e3
Binary files /dev/null and b/layers/water/mapping.png differ
diff --git a/layers/water/mapping.yaml b/layers/water/mapping.yaml
index 5e74ec6..e77772a 100644
--- a/layers/water/mapping.yaml
+++ b/layers/water/mapping.yaml
@@ -52,25 +52,3 @@ tables:
       - drain
       - ditch
     type: polygon
-  water_linestring:
-    fields:
-    - name: osm_id
-      type: id
-    - name: geometry
-      type: geometry
-    - name: waterway
-      type: mapping_value
-    - key: name
-      name: name
-      type: string
-    - name: name_en
-      key: name:en
-      type: string
-    mapping:
-      waterway:
-      - stream
-      - river
-      - canal
-      - drain
-      - ditch
-    type: linestring
diff --git a/layers/water/water.yaml b/layers/water/water.yaml
index 69e52b9..50bafe3 100644
--- a/layers/water/water.yaml
+++ b/layers/water/water.yaml
@@ -1,7 +1,15 @@
 layer:
   id: "water"
   description: |
-      Water polygons and linestrings representing oceans, lakes.
+      Water polygons representing oceans and lakes. Covered watered areas are excluded (`covered=yes`).
+      Until z6 all water originates from Natural Earth. To get a more correct display of the south pole you should also
+      style the covering ice shelves over the water.
+      Water from OpenStreetMap after z7 is split into many smaller polygons to improve rendering performance.
+      This however can lead to less rendering options in clients since these boundaries show up. So you might not be
+      able to use border styling for ocean water features.
+  fields:
+    class: |
+        Either `ocean`, `lake` or `river`.
   buffer_size: 4
   datasource:
     query: (SELECT geom, class FROM layer_water(!bbox!, z(!scale_denominator!))) AS t