Document water and remove obsolete mapping

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