Merge pull request #215 from nrrkeene/master

Added proper documentation

3 files changed, 60 insertions, 6 deletions

diff --git a/keyboard/ergodox_ez/keymaps/ordinary/ordinary-base.png b/keyboard/ergodox_ez/keymaps/ordinary/ordinary-base.png
index b32b95533c..d5d00f2403 100644
--- a/keyboard/ergodox_ez/keymaps/ordinary/ordinary-base.png
+++ b/keyboard/ergodox_ez/keymaps/ordinary/ordinary-base.png
diff --git a/keyboard/ergodox_ez/keymaps/ordinary/ordinary-base.txt b/keyboard/ergodox_ez/keymaps/ordinary/ordinary-base.txt
index 727775ea2c..046b75786a 100644
--- a/keyboard/ergodox_ez/keymaps/ordinary/ordinary-base.txt
+++ b/keyboard/ergodox_ez/keymaps/ordinary/ordinary-base.txt
@@ -1,8 +1,8 @@
 [{x:3.5},"#\n3",{x:10.5},"*\n8"],
 [{y:-0.875,x:2.5},"@\n2",{x:1},"$\n4",{x:8.5},"&\n7",{x:1},"(\n9"],
 [{y:-0.875,x:5.5},"%\n5",{c:"#ff4444"},"Esc",{x:4.5,c:"#cccccc"},"_\n\n\n\n\n\n-","^\n6"],
-[{y:-0.875,c:"#73ab6a",w:1.5},"~\n\n\n\n\n\n`",{c:"#cccccc"},"!\n1",{x:14.5},")\n0",{t:"#000000\n\n\n\n#0000ff",w:1.5},"+\n\n\n\n\n\n="],
-[{y:-0.375,x:3.5,t:"#000000"},"E",{x:10.5},"I"],
+[{y:-0.875,c:"#73ab6a",w:1.5},"~\n\n\n\n\n\n`",{c:"#cccccc"},"!\n1",{x:14.5},")\n0",{w:1.5},"+\n\n\n\n\n\n="],
+[{y:-0.375,x:3.5},"E",{x:10.5},"I"],
 [{y:-0.875,x:2.5},"W",{x:1},"R",{x:8.5},"U",{x:1},"O"],
 [{y:-0.875,x:5.5},"T",{h:1.5},"{\n\n\n\n\n\n[",{x:4.5,h:1.5},"}\n\n\n\n\n\n]","Y"],
 [{y:-0.875,c:"#73ab6a",w:1.5},"Tab",{c:"#cccccc"},"Q",{x:14.5},"P",{c:"#2277ff",fa:[0,0,0,1],w:1.5},"|\n\\\nMedia\nL2"],
@@ -14,7 +14,7 @@
 [{y:-0.75,x:3.5,c:"#cccccc"},"C",{x:10.5},"<\n,"],
 [{y:-0.875,x:2.5},"X",{x:1},"V",{x:8.5},"M",{x:1},">\n."],
 [{y:-0.875,x:5.5},"B",{x:6.5},"N"],
-[{y:-0.875,c:"#2277ff",w:1.5},"Capitals\n\n\nShift",{c:"#cccccc"},"Z\n\nCtrl",{x:14.5},"?\n/\nCtrl",{c:"#2277ff",w:1.5},"\n\nCapitals\nShift"],
+[{y:-0.875,c:"#2277ff",w:1.5},"Capitals\n\n\nShift",{c:"#cccccc"},"Z",{x:14.5},"?\n/",{c:"#2277ff",w:1.5},"\n\nCapitals\nShift"],
 [{y:-0.375,x:3.5,c:"#77aaff"},"Option\n\n\nLAlt",{x:10.5},"Option\n\n\nRAlt"],
 [{y:-0.875,x:2.5},"Hyper",{x:1},"Cmd\n\n\nSuper",{x:8.5},"Cmd\n\n\nSuper",{x:1},"Hyper"],
 [{y:-0.75,x:0.5},"Ctrl\n\n\nLCtrl","Meh",{x:14.5},"Meh","Ctrl\n\n\nRCtrl"],
diff --git a/keyboard/ergodox_ez/keymaps/ordinary/readme.md b/keyboard/ergodox_ez/keymaps/ordinary/readme.md
index 1cfea06dd0..6534f481a1 100644
--- a/keyboard/ergodox_ez/keymaps/ordinary/readme.md
+++ b/keyboard/ergodox_ez/keymaps/ordinary/readme.md
@@ -1,9 +1,63 @@
-# The Ordinary Layout, a familiar and powerful layout
+# The Ordinary Layout, a familiar and powerful layout #
 
-The Ordinary Layout is intended to be unremarkably mundane and remarkably useful. This layout maintains most key positions from common QWERTY keyboards and features enhanced Symbol and Media layers compared to the default Ergodox EZ layout.
+The Ordinary Layout is intended to be unremarkably mundane and remarkably useful. This layout maintains most key positions from common QWERTY keyboards, and it features enhanced Symbol and Media layers compared to the default Ergodox EZ layout.
 
-Full details about the rationale behind this layout [are available](http://nicholas.rinard.us/2016/03/ergodox-ez-layout.html).
+The Ordinary Layout is supposed to look mostly like a normal keyboard, except in the ways that the Ergodox key arrangement is unique. The thumbs are responsible for space, enter, plus both forward and backward delete; with only a couple exceptions, all other keys are in the same place they are found on traditional keyboards.
+
+Nicholas Keene
+ordinarylayout@nicholaskeene.com
+no rights reserved, use for any purposes, credit me if you are a nice person
+
+## The Base Layout ##
+
+* The yellow keys are text navigation and manipulation
+* The dark blue keys are shift keys: case shift (traditional shift), symbol shift, and media shift
+* The light blue keys are modifiers: traditional Control, Option, and C	ommand keys, plus Hyper and Meh
+* The two green keys, tab and tilde, are in the typical places to ease use of the Application Switcher
+* The red keys is Escape, one of the few buttons which is in an atypical position
 
 ![Ordinary base layout](ordinary-base.png)
+
+This layout puts the modifier keys along the bottom of the keyboard where they are on most layouts. They are in the regular order, with the addition of Hyper and Meh keys. The shift key (case shift) is in the prevalent location. The primo slots usually wasted on Caps Lock and Enter are instead used for the Symbol Shift key which promotes use of the Symbols layer. On the right side of the layout, the Symbol and Media shift keys also double as character keys -- quote and backslash, respectively -- so that touch typists can continue to find those punctuation marks in the right place.
+
+Other than the yellow keys, the only buttons which move to new locations are the Brackets and Dash and Escape. Most touch typists dont touch-type brackets or dash anyway, so only Escape really requires retraining of muscle memory.
+
+The four big yellow keys are arranged differently than in the default Ergodox EZ layout. The Ordinary Layout here copies the design of the old Fingerworks TouchStream keyboard, but also reflects the natural presumptions of the author -- me!; I type the space character with my right hand, and to me it makes sense for the two delete keys to be next to one another.
+
+The Forward Tab and Backward Tab keys are there mostly because I ended up with two extra buttons and needed something to do with them. My muscle memory from using the Truly Ergonomic Keyboard makes me look for the Tab key with my right index finger, so it is handy to have this redundant Tab, and the idea with the Backward Tab key is that it becomes easy to navigate text fields in forms, or to indent/unindent code.
+
+## The Symbols Layout ##
+
+* The periwinkle keys are the eponymous symbols
+* The gray keys are F-Keys
+* The green keys are a proper number pad
+* The red Escape key is found in the "right" location on this layer
+* The yellow keys are the *reverse* of the yellow keys on the base layer
+* The dark blue Media key means that the Media layer is accessible with the left hand
+
 ![Ordinary symbol layout](ordinary-symbol.png)
+
+The Ergodox EZ ships with the "Coder Layer" which I like to call the Symbols layer. There are some significant improvements in The Ordinary Layout over the default layout.
+
+The symbol keys are mostly the same as on the default layout, which did a good job in this regard, but with a few enhancements:
+* Angle brackets on this layer mean that curly, square, and angle brackets are all available on different layers of the same two buttons. Also, they mean that all kinds of brackets, including parentheses, are available on both the Base and Symbols layers.
+* The slash, backslash, and pipe characters are grouped together as a memory aid.
+* The & and | symbols are juxtaposed as a memory aid
+
+The number pad area here, in green, includes all four arithmetic operations in the same order found on most number pads. This layout also has an Enter key, and importantly the key codes emitted by this number pad are *number pad specific key codes*, not regular keyboard key codes. Some software distinguishes keypad codes so users now have access to a fully realized number pad when using The Ordinary Layout.
+
+The Escape key's true home is in the top left corner of the keyboard, so on this layer it can be found there. And on the Symbols layer, the Tab key switches to become a Media key, so press Symbols then Media to access the Media layer using the left hand.
+
+Finally, consider the yellow text-nav keys. In the Symbols layer, these are *reversed* from the base layer, with most keys mirrored, but the Delete keys shifted to maintain the directional significance of their arrangement. This is powerful! Often I find myself using the mouse with my right hand, and the left hand needs to press Enter. Instead of reaching the left hand over to the right side of the keyboard, now I simply tap Symbols to reverse the yellow keys, and Enter is right where it should be.
+
+## The Media Layout ##
+
+* The light turquoise keys move the mouse or the text cursor
+* The dark turquoise keys scroll
+* The light purple keys signal Web and Audio applications
+* The dark purple keys signal the operating system
+* The red Escape key is, again, found in the "right" location
+
 ![Ordinary media layout](ordinary-media.png)
+
+This layer was inspired by the Media layer on the Ergodox EZ but takes it farther. The Fingerworks TouchStream had a very useful feature for controlling the text cursor easily and this layer does something similar. The left hand can move the mouse, the right hand moves the text cursor, in all four directions, in small or large increments. This greatly enhances navigation in text documents.