diff --git a/flatmap-basemap/README.md b/flatmap-basemap/README.md
index e6936fcd..fb52107a 100644
--- a/flatmap-basemap/README.md
+++ b/flatmap-basemap/README.md
@@ -5,10 +5,10 @@ See [README.md](../README.md) in the parent directory for instructions on how to
 
 ## Differences from OpenMapTiles
 
-- `transportation_name` layer does not abbreviate road names yet
-- `poi` layer missing the `agg_stop` tag
-- Paths are visible at z13 in `transportation` and `transportation_name` layers instead of z14 in OpenMapTiles, to
-  revert this behavior set `--transportation-z13-paths=false`
+- Road name abbreviations are not implemented yet in the `transportation_name` layer
+- `agg_stop` tag not implemented yet in the `poi` layer
+- Paths are visible at z13 and z14 in `transportation` and `transportation_name` layers instead of just z14 in
+  OpenMapTiles, to revert this behavior set `--transportation-z13-paths=false`
 - `brunnel` tag is excluded from `transportation_name` layer to avoid breaking apart long `transportation_name`
   lines, to revert this behavior set `--transportation-name-brunnel=true`
 
@@ -18,7 +18,8 @@ See [README.md](../README.md) in the parent directory for instructions on how to
 the [generated](./src/main/java/com/onthegomap/flatmap/basemap/generated) package from an OpenMapTiles tag in GitHub:
 
 - [OpenMapTilesSchema](./src/main/java/com/onthegomap/flatmap/basemap/generated/OpenMapTilesSchema.java)
-  contains an interface for each layer with constants for the name, attributes, and their allowed values
+  contains an interface for each layer with constants for the name, attributes, and allowed values for each tag in that
+  layer
 - [Tables](./src/main/java/com/onthegomap/flatmap/basemap/generated/Tables.java)
   contains a record for each table that OpenMapTiles [imposm3](https://github.com/omniscale/imposm3) configuration
   generates (along with the tag-filtering expression) so layers can listen on instances of those records instead of
@@ -28,8 +29,8 @@ The [layers](./src/main/java/com/onthegomap/flatmap/basemap/layers) package cont
 each layer from OpenMapTiles. Layers define how source features (or parsed imposm3 table rows) map to vector tile
 features, and logic for post-processing tile geometries.
 
-[BasemapProfile](./src/main/java/com/onthegomap/flatmap/basemap/BasemapProfile.java)
-dispatches source features to layers and merges the results.
+[BasemapProfile](./src/main/java/com/onthegomap/flatmap/basemap/BasemapProfile.java) dispatches source features to layer
+handlers and merges the results.
 
 [BasemapMain](./src/main/java/com/onthegomap/flatmap/basemap/BasemapMain.java) is the main driver that registers source
 data and output location.
@@ -53,5 +54,5 @@ OpenMapTiles.
 The OpenMapTiles schema (or "look and feel") is licensed under [CC-BY 4.0](http://creativecommons.org/licenses/by/4.0/),
 so any map derived from that schema
 must [visibly credit OpenMapTiles](https://github.com/openmaptiles/openmaptiles/blob/master/LICENSE.md#design-license-cc-by-40)
-. It also uses OpenStreetMap data so you
+. It also uses OpenStreetMap data, so you
 must [visibly credit OpenStreetMap contributors](https://www.openstreetmap.org/copyright).