diff --git a/Makefile b/Makefile
index 342a6d8..27bdcc0 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 layers/water/README.md layers/building/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 layers/building/README.md layers/highway/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
@@ -9,6 +9,9 @@ build/mapping.yaml:
 build/tileset.sql:
 	mkdir -p build && generate-sql openmaptiles.yaml > build/tileset.sql
 
+layers/highway/README.md:
+	generate-doc layers/highway/highway.yaml --diagram layers/highway/mapping > layers/highway/README.md
+
 layers/railway/README.md:
 	generate-doc layers/railway/railway.yaml --diagram layers/railway/mapping > layers/railway/README.md
 
diff --git a/layers/highway/README.md b/layers/highway/README.md
new file mode 100644
index 0000000..ee88c25
--- /dev/null
+++ b/layers/highway/README.md
@@ -0,0 +1,30 @@
+# highway
+
+Roads or [`highway`](http://wiki.openstreetmap.org/wiki/Key:highway) in OpenStreetMap lingo.
+This layer is directly derived from the OSM road hierarchy which is why it is called `highway`. Only
+at zoom level 4 to 7 some major highways from Natural Earth are used otherwise it is only OSM data.
+It contains all roads from motorways to primary, secondary and tertiary roads to residential roads and
+foot paths. Styling the roads is the most essential part of the map. If you can put enough effort into it
+makes sense to carefully style each `subclass`. For more comfortable styling you can also just style the roads
+by `class`. Roads can have different properties, a road can have `oneway=yes` and `bridge=yes` at the same time.
+These properties are reflected in the field `properties`.
+This layer is not meant for labelling the roads (the purpose of the layer `highway_name`).
+
+The `highway` layer also contains polygons for things like plazas.
+
+## Fields
+
+- **class**: Either `motorway`, `major_road` (containing `trunk`, `primary`, `secondary` and `tertiary` roads) and `minor_road` (less important roads in the hierarchy like `residential` or `service`) or `path` for
+non vehicle paths (such as `cycleway` or `footpath`).
+- **subclass**: Original value of the [`highway`](http://wiki.openstreetmap.org/wiki/Key:highway) tag. Use this to do more
+precise styling.
+- **properties**: Additional properties describing the nature of road.
+The properties `bridge` and `tunnel` can be combined with `oneway` as well. So to style all bridges the same you
+should style both the properties `bridge` and `bridge:oneway`.
+Properties can be one of `bridge:oneway`, `tunnel:oneway`, `ramp`, `ford`, `bridge`, `tunnel` or`oneway`.
+
+## Mapping
+
+![](mapping.png)
+
+
diff --git a/layers/highway/highway.yaml b/layers/highway/highway.yaml
index 7ffda08..f028095 100644
--- a/layers/highway/highway.yaml
+++ b/layers/highway/highway.yaml
@@ -1,12 +1,31 @@
 layer:
   id: "highway"
   description: |
-      [OpenStreetMap highway] which is used for roads, paths and cycletracks
-      and other recognised routes on land.
+      Roads or [`highway`](http://wiki.openstreetmap.org/wiki/Key:highway) in OpenStreetMap lingo.
+      This layer is directly derived from the OSM road hierarchy which is why it is called `highway`. Only
+      at zoom level 4 to 7 some major highways from Natural Earth are used otherwise it is only OSM data.
+      It contains all roads from motorways to primary, secondary and tertiary roads to residential roads and
+      foot paths. Styling the roads is the most essential part of the map. If you can put enough effort into it
+      makes sense to carefully style each `subclass`. For more comfortable styling you can also just style the roads
+      by `class`. Roads can have different properties, a road can have `oneway=yes` and `bridge=yes` at the same time.
+      These properties are reflected in the field `properties`.
+      This layer is not meant for labelling the roads (the purpose of the layer `highway_name`).
+
+      The `highway` layer also contains polygons for things like plazas.
   buffer_size: 4
   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
+    class: |
+        Either `motorway`, `major_road` (containing `trunk`, `primary`, `secondary` and `tertiary` roads) and `minor_road` (less important roads in the hierarchy like `residential` or `service`) or `path` for
+        non vehicle paths (such as `cycleway` or `footpath`).
+    subclass: |
+        Original value of the [`highway`](http://wiki.openstreetmap.org/wiki/Key:highway) tag. Use this to do more
+        precise styling.
+    properties: |
+        Additional properties describing the nature of road.
+        The properties `bridge` and `tunnel` can be combined with `oneway` as well. So to style all bridges the same you
+        should style both the properties `bridge` and `bridge:oneway`.
+        Properties can be one of `bridge:oneway`, `tunnel:oneway`, `ramp`, `ford`, `bridge`, `tunnel` or`oneway`.
   datasource:
     geometry_field: geometry
     srid: 900913
diff --git a/layers/highway/mapping.png b/layers/highway/mapping.png
new file mode 100644
index 0000000..363342b
Binary files /dev/null and b/layers/highway/mapping.png differ
diff --git a/layers/highway/types.sql b/layers/highway/types.sql
index 1696367..f7346fa 100644
--- a/layers/highway/types.sql
+++ b/layers/highway/types.sql
@@ -40,4 +40,4 @@ CREATE OR REPLACE FUNCTION to_highway_properties(is_bridge boolean, is_tunnel bo
          WHEN is_oneway THEN 'oneway'::highway_properties
         ELSE NULL
     END;
-$$ LANGUAGE SQL IMMUTABLE STRICT;
+$$ LANGUAGE SQL IMMUTABLE;