diff --git a/docs/reference/modal-editing/speaking-vim.md b/docs/reference/modal-editing/speaking-vim.md
index 896fc585..a5e15b64 100644
--- a/docs/reference/modal-editing/speaking-vim.md
+++ b/docs/reference/modal-editing/speaking-vim.md
@@ -1,36 +1,78 @@
 # Learning to speak Vim
 
-Neovim is easier to learn and gain much more benefit from if you learn to speak commands as sentences.
+Learning to speak the language of vim-style editing significantly accelerates the performance of communicating with the computer.
 
-First learn some verbs:
+The structure of the language takes one of the forms:
 
-- `c` change
-- `d` delete
-- `g` go,
-- `v` visual select
-- `y` yank (copy)
 
-Then use those verbs with some modifiers
+!!! TIP "keys are mnemonic or regex and have capitalised variants"
+    Keys were designed to be mnemonic where possible, e.g. ++"d"++ for delete and  ++"c"++ for change
 
-- `'` mark
-- `{ }` beginning/end of paragraph
-- `0` start of line
-- `^` first non white-space character of line
-- `$` end of line
-- `a` around
-- `f` find (includes character)
-- `i` inside a range (e.g. word, paren,)
-- `s` surround
-- `t` till (move just before specified character)
+    Common regular expression scopes are used, e.g. ++0++ first character, ++"$"++ last character
+
+    Keys often have a variant of the action in the capitalised key, e.g. ++shift++ ++"c"++ changes to end of line
+
+
+## Actions
+
+First learn some verbs, these are your actions:
+
+++"c"++ change
+
+++"d"++ delete
+
+++"g"++ go
+
+++"v"++ visual select
+
+++"y"++ yank (copy)
+
+!!! TIP "Double tap to act on current line"
+    ++"d"++ ++"d"++ deletes the current line
+
+    ++"y"++ ++"y"++ yanks (copies) the current line
+
+
+## Motions
+
+Then use those verbs with some motions
+
+++"%"++ matching paren `() [] {}` (toggle between open and closed paren)
+
+++grave++ mark character (specify existing mark character)
+
+++open-brace++ ++close-brace++ beginning/end of paragraph
+
+++0++ start of line
+
+++"^"++ first non white-space character of line
+
+++"$"++ end of line
+
+++"a"++ around
+
+++"f"++ find specified character forward, ++"F"++ find backward
+
+++"i"++ inside a range (e.g. a text object like word, or parens)
+
+++"s"++ surround
+
+++"t"++ till (move just before specified character)
+
+
+## Text Objects
 
 Then learn the text objects you can apply verbs and modifiers too
 
-- `b` block/parentheses
-- `p` paragraph,
-- `s` sentence
-- `t` tag e.g. html/xml
-- `w` word
+++"b"++ **block/parentheses** a text block or text between parens
+
+++"p"++ **paragraph** text to the next blank line
 
+++"s"++ **sentence** text to a full stop character
+
+++"t"++ **tag** e.g. html/xml tag and its contents
+
+++"w"++ **word** - start of next word, ++"W"++ ignores punctuation
 
 ## Examples of speaking Vim
 
@@ -56,3 +98,11 @@ Practice speaking evil with these examples
 | `y y`       | yank (copy) current line                                              |
 | `y w`       | yank (copy) current word                                              |
 | `y @ a`     | yank (copy) to mark `a` (`m a` creates a mark called `a`)             |
+
+
+<!--
+- actions motion
+- actions number motion
+- actions text object
+- actions number text object
+-->