diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index c1686f9..4bb8bb4 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -83,28 +83,28 @@ See [DESIGN.md](DESIGN.md) for a more thorough description of changes.
 
 Major version update.
 
-This breaks 1.x configs. The format may change slightly before leaving beta,
+This breaks 1.x configs. The format may ~~change slightly~~ (see [2.3.0-rc](#v2.3.0-rc)) before leaving beta,
 but once it does should remain backwards compatible for the foreseeable future.
 
 A non exhaustive list of changes can be found below. It is best to forget
 everything you know and read man page anew.
 
-	- Eliminate layer inheritance in favour of simple types.
-	(layouts are now defined with `:layout` instead of `:main`)
-	- Macros are now repeatable.
-	- Overload now accepts a hold threshold timeout.
-	- Config files are now vendor/product id oriented.
-	- SIGUSR1 now triggers a config reload.
-	- Modifiers are layers by default and can be extended directly.
-	- Config files now end in `.conf`.
-	- `layert()` is now `toggle()`.
-	- All layers are 'modifier layers' (terminological change)
-	- Eliminate the dedicated modifer layout.
-	- Modifiers no longer apply to key sequences defined within a layer.
-	  (Layer entries are now always executed verbatim.)
-
-	  The old behaviour was unintuitive and can be emulated using nested
-	  layers if necessary.
+ - Eliminate layer inheritance in favour of simple types.
+ (layouts are now defined with `:layout` instead of `:main`)
+ - Macros are now repeatable.
+ - Overload now accepts a hold threshold timeout.
+ - Config files are now vendor/product id oriented.
+ - SIGUSR1 now triggers a config reload.
+ - Modifiers are layers by default and can be extended directly.
+ - Config files now end in `.conf`.
+ - `layert()` is now `toggle()`.
+ - All layers are 'modifier layers' (terminological change)
+ - Eliminate the dedicated modifer layout.
+ - Modifiers no longer apply to key sequences defined within a layer.
+   (Layer entries are now always executed verbatim.)
+
+   The old behaviour was unintuitive and can be emulated using nested
+   layers if necessary.
 
 For most old configs transitioning should be a simple matter of changing
 the file extension from `.cfg` to `.conf`, replacing `layert` with
diff --git a/docs/DESIGN.md b/docs/DESIGN.md
index 92f87cd..27eca4d 100644
--- a/docs/DESIGN.md
+++ b/docs/DESIGN.md
@@ -53,8 +53,8 @@ and enhancements.
 	l = right
 ```
 
-    will cause `control+h` to produce `left` (rather than `C-left`), while
-    `control+capslock+h` will produce `C-left`, as one might intuit.
+will cause `capslock+h` to produce `left` (rather than `C-left`), while
+`control+capslock+h` will produce `C-left`, as one might intuit.
 
   - Abolished layer types. Notably, the concept of a 'layout' no longer exists.