diff --git a/Makefile b/Makefile
index 8ff02da..eeebeb9 100644
--- a/Makefile
+++ b/Makefile
@@ -1,4 +1,4 @@
-all: build/openmaptiles.tm2source/data.yml build/mapping.yaml build/tileset.sql
+all: build/openmaptiles.tm2source/data.yml build/mapping.yaml build/tileset.sql layers/railway/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,5 +9,8 @@ build/mapping.yaml:
 build/tileset.sql:
 	mkdir -p build && generate-sql openmaptiles.yaml > build/tileset.sql
 
+layers/railway/README.md:
+	generate-doc layers/railway/railway.yaml --diagram layers/railway/mapping > layers/railway/README.md
+
 clean:
-	rm -f build/openmaptiles.tm2source/data.yml && rm -f build/mapping.yaml && rm -f build/tileset.sql
+	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/railway/README.md b/layers/railway/README.md
new file mode 100644
index 0000000..8a1bc51
--- /dev/null
+++ b/layers/railway/README.md
@@ -0,0 +1,19 @@
+# railway
+
+The `railway` layer contains linestrings marking tracks from [OSM Railways](http://wiki.openstreetmap.org/wiki/Railways).
+It contains tracks for [passenger and freight trains]() and smaller tracks for [Trams](http://wiki.openstreetmap.org/wiki/Tag:railway%3Dtram) or [similar](http://wiki.openstreetmap.org/wiki/Tag:railway%3Dlight_rail) vehicles. But also tracks for [subways](http://wiki.openstreetmap.org/wiki/Tag:railway%3Dsubway), [narrow-gauge trains](http://wiki.openstreetmap.org/wiki/Tag:railway%3Dnarrow_gauge) or [historic trains](http://wiki.openstreetmap.org/wiki/Tag:railway%3Dpreserved).
+Non mainline tracks (marked with class `minor_rail`) used for [storage of trains](http://wiki.openstreetmap.org/wiki/Tag:service%3Dyard) and [maintenance](http://wiki.openstreetmap.org/wiki/Tag:service%3Dsiding) are contained in the highest zoom levels and should be styled more subtle than the mainline tracks with class `rail`.
+
+## Fields
+
+- **class**: Divides the track into mainline tracks (class `rail`) and less important tracks
+used for maintenance (class `minor_rail`).
+- **subclass**: Original value of the [`railway`](http://wiki.openstreetmap.org/wiki/Key:railway) can be one of
+`rail`, `light_rail`, `subway`, `narrow_gauge`, `preserved`, `tram`.
+- **properties**: Additional properties describing the nature of tracks. Can be either `bridge` or `tunnel`.
+
+## Mapping
+
+![](mapping.png)
+
+
diff --git a/layers/railway/mapping b/layers/railway/mapping
new file mode 100644
index 0000000..d068987
--- /dev/null
+++ b/layers/railway/mapping
@@ -0,0 +1,14 @@
+digraph "Imposm Mapping" {
+	graph [rankdir=LR ranksep=3]
+		subgraph railway_linestring {
+			node [fixed_size=shape "width:"=20]
+				railway_linestring [shape=box]
+				key_railway [label=railway shape=box]
+					key_railway -> railway_linestring [label="rail
+light_rail
+subway
+narrow_gauge
+preserved
+tram"]
+		}
+}
\ No newline at end of file
diff --git a/layers/railway/mapping.png b/layers/railway/mapping.png
new file mode 100644
index 0000000..52a4723
Binary files /dev/null and b/layers/railway/mapping.png differ
diff --git a/layers/railway/railway.sql b/layers/railway/railway.sql
index 5fc66fe..3d1e77c 100644
--- a/layers/railway/railway.sql
+++ b/layers/railway/railway.sql
@@ -13,25 +13,17 @@ CREATE OR REPLACE FUNCTION railway_brunnel(is_bridge boolean, is_tunnel boolean)
     END;
 $$ LANGUAGE SQL IMMUTABLE;
 
-CREATE OR REPLACE VIEW railway_z13 AS (
-    SELECT * FROM osm_railway_linestring
-    WHERE railway = 'rail' AND service=''
-);
-
-CREATE OR REPLACE VIEW railway_z14 AS (
-    SELECT * FROM osm_railway_linestring
-);
-
 CREATE OR REPLACE FUNCTION layer_railway(bbox geometry, zoom_level int)
-RETURNS TABLE(osm_id bigint, geometry geometry, class text, subclass text, brunnel text) AS $$
+RETURNS TABLE(osm_id bigint, geometry geometry, class text, subclass text, properties railway_properties) AS $$
     SELECT osm_id, geometry,
         railway_class(railway, service) AS class,
         railway AS subclass,
-        railway_brunnel(is_bridge, is_tunnel) AS brunnel
+        to_railway_properties(is_bridge, is_tunnel) AS properties
     FROM (
-        SELECT * FROM railway_z13 WHERE zoom_level = 13
+        SELECT * FROM osm_railway_linestring
+        WHERE zoom_level = 13 AND railway = 'rail' AND service=''
         UNION ALL
-        SELECT * FROM railway_z14 WHERE zoom_level >= 14
+        SELECT * FROM osm_railway_linestring WHERE zoom_level >= 14
     ) AS zoom_levels
     WHERE geometry && bbox
     ORDER BY z_order ASC;
diff --git a/layers/railway/railway.yaml b/layers/railway/railway.yaml
index 6290e22..913f4d6 100644
--- a/layers/railway/railway.yaml
+++ b/layers/railway/railway.yaml
@@ -1,11 +1,24 @@
 layer:
   id: "railway"
-  description: Rail
+  description: |
+      The `railway` layer contains linestrings marking tracks from [OSM Railways](http://wiki.openstreetmap.org/wiki/Railways).
+      It contains tracks for [passenger and freight trains]() and smaller tracks for [Trams](http://wiki.openstreetmap.org/wiki/Tag:railway%3Dtram) or [similar](http://wiki.openstreetmap.org/wiki/Tag:railway%3Dlight_rail) vehicles. But also tracks for [subways](http://wiki.openstreetmap.org/wiki/Tag:railway%3Dsubway), [narrow-gauge trains](http://wiki.openstreetmap.org/wiki/Tag:railway%3Dnarrow_gauge) or [historic trains](http://wiki.openstreetmap.org/wiki/Tag:railway%3Dpreserved).
+      Non mainline tracks (marked with class `minor_rail`) used for [storage of trains](http://wiki.openstreetmap.org/wiki/Tag:service%3Dyard) and [maintenance](http://wiki.openstreetmap.org/wiki/Tag:service%3Dsiding) are contained in the highest zoom levels and should be styled more subtle than the mainline tracks with class `rail`.
+  fields:
+    class: |
+        Divides the track into mainline tracks (class `rail`) and less important tracks
+        used for maintenance (class `minor_rail`).
+    subclass: |
+        Original value of the [`railway`](http://wiki.openstreetmap.org/wiki/Key:railway) can be one of
+        `rail`, `light_rail`, `subway`, `narrow_gauge`, `preserved`, `tram`.
+    properties: |
+        Additional properties describing the nature of tracks. Can be either `bridge` or `tunnel`.
   buffer_size: 4
   datasource:
     geometry_field: geometry
-    query: (SELECT geometry, class, subclass, brunnel FROM layer_railway(!bbox!, z(!scale_denominator!))) AS t
+    query: (SELECT geometry, class, subclass, properties::text FROM layer_railway(!bbox!, z(!scale_denominator!))) AS t
 schema:
+  - ./types.sql
   - ./railway.sql
 datasources:
   - type: imposm3
diff --git a/layers/railway/types.sql b/layers/railway/types.sql
new file mode 100644
index 0000000..e323edd
--- /dev/null
+++ b/layers/railway/types.sql
@@ -0,0 +1,15 @@
+DO $$
+BEGIN
+    IF NOT EXISTS (SELECT 1 FROM pg_type WHERE typname = 'railway_properties') THEN
+        CREATE TYPE railway_properties AS ENUM ('bridge', 'tunnel');
+    END IF;
+END
+$$;
+
+CREATE OR REPLACE FUNCTION to_railway_properties(is_bridge boolean, is_tunnel boolean) RETURNS railway_properties AS $$
+    SELECT CASE
+         WHEN is_bridge THEN 'bridge'::railway_properties
+         WHEN is_tunnel THEN 'tunnel'::railway_properties
+        ELSE NULL
+    END;
+$$ LANGUAGE SQL IMMUTABLE;