More docs clarifications (#659)

Author: pokey

docs/contributing/CONTRIBUTING.md

@@ -1,7 +1,7 @@
 # Contributing
 
 Welcome! So glad you've decided to help make Cursorless better. Once you've
-learned how to [install](#installation) and [run / test a local copy of the
+learned how to [set up](#initial-setup) and [run / test a local copy of the
 extension](#running--testing-extension-locally), you may want to check out the
 [Cursorless API docs](api) to learn more about how Cursorless works. You may also find the [VSCode API docs](https://code.visualstudio.com/api) helpful to learn about VSCode extension development.
 
@@ -30,8 +30,8 @@ Extension" or "Extension Tests".
 
 We use [`pre-commit`](https://pre-commit.com/) to automate autoformatting.
 Autoformatters will automatically run on PRs in CI, but you can also run them
-locally or install pre-commit hooks as described in the `pre-commit`
-documentation.
+locally or install pre-commit hooks as described in the
+[`pre-commit` documentation](https://pre-commit.com/).
 
 ## Running docs site locally
 

docs/user/README.md

@@ -14,7 +14,9 @@ Note: If you'd like to customize any of the spoken forms, please see the [docume
 
 ## Overview
 
-Every cursorless command consists of an action performed on a target. For example, the command `"chuck blue air"` deletes the token with a blue hat over the `"a"`. In this command, the action is `"chuck"` (delete), and the target is `"blue air"`. There are no actions without at least one target.
+Every cursorless command consists of an action performed on a target. For example, the command `"chuck bat"` deletes the token with a hat over the `b`. In this command, the action is `"chuck"` (delete), and the target is `"bat"`. There are no actions without at least one target.
+
+![`"chuck bat"`](images/chuckBat.gif)
 
 ## Targets
 
@@ -47,43 +49,47 @@ Combining this with an action, we might say `"take blue air"` to select the toke
 
 ###### Colors
 
-The following colors are supported:
+The following colors are supported. Note that to target the default (gray) hat you don't need to specify a color.
 
-| Spoken form | Visible color | Internal ID |
-| ----------- | ------------- | ----------- |
-| `"blue"`    | Blue          | `blue`      |
-| `"green"`   | Green         | `green`     |
-| `"rose"`    | Red           | `rose`      |
-| `"squash"`  | Yellow        | `yellow`    |
-| `"plum"`    | Pink          | `pink`      |
+| Spoken form | Color   | Internal ID  | Enabled by default? |
+| ----------- | ------- | ------------ | ------------------- |
+| N/A         | grey    | `default`    | ✅                  |
+| `"blue"`    | blue    | `blue`       | ✅                  |
+| `"green"`   | green   | `green`      | ✅                  |
+| `"red"`     | red     | `red`        | ✅                  |
+| `"pink"`    | pink    | `pink`       | ✅                  |
+| `"yellow"`  | yellow  | `yellow`     | ✅                  |
+| `"navy"`    | navy    | `userColor1` | ❌                  |
+| `"apricot"` | apricot | `userColor2` | ❌                  |
 
 You can enable or disable colors in your VSCode settings, by searching for `cursorless.hatEnablement.colors` and checking the box next to the internal ID for the given shape as listed above.
 
 You can also tweak the visible colors for any of these colors in your VSCode settings, by searching for `cursorless.colors` and changing the hex color code next to the internal ID for the given shape as listed above. Note that you can configure different colors for dark and light themes.
 
 If you find these color names unintuitive / tough to remember, their
 spoken forms can be [customized](customization.md) like any other spoken form
-in cursorless. If you change a spoken form to be more than one syllable, you
+in Cursorless. If you change a spoken form to be more than one syllable, you
 can change the penalty in the `cursorless.hatPenalties.colors` setting to the
-number of syllables you use, so that cursorless can optimize hat allocation to
+number of syllables you use, so that Cursorless can optimize hat allocation to
 minimize syllables.
 
 ###### Shapes
 
-The following shapes are supported:
-
-| Spoken form | Internal ID  | Shape                                           | Enabled by default? |
-| ----------- | ------------ | ----------------------------------------------- | ------------------- |
-| `"ex"`      | `ex`         | ![Ex](../../images/hats/ex.svg)                 | ❌                  |
-| `"fox"`     | `fox`        | ![Fox](../../images/hats/fox.svg)               | ❌                  |
-| `"wing"`    | `wing`       | ![Wing](../../images/hats/wing.svg)             | ❌                  |
-| `"hole"`    | `hole`       | ![Hole](../../images/hats/hole.svg)             | ❌                  |
-| `"frame"`   | `frame`      | ![Frame](../../images/hats/frame.svg)           | ❌                  |
-| `"curve"`   | `curve`      | ![Curve](../../images/hats/curve.svg)           | ❌                  |
-| `"eye"`     | `eye`        | ![Eye](../../images/hats/eye.svg)               | ❌                  |
-| `"play"`    | `play`       | ![Play](../../images/hats/play.svg)             | ❌                  |
-| `"cross"`   | `crosshairs` | ![Crosshairs](../../images/hats/crosshairs.svg) | ❌                  |
-| `"bolt"`    | `bolt`       | ![Bolt](../../images/hats/bolt.svg)             | ❌                  |
+The following shapes are supported. Note that to target the default (dot) shape you don't need to specify a shape.
+
+| Spoken form | Shape                                           | Internal ID  | Enabled by default? |
+| ----------- | ----------------------------------------------- | ------------ | ------------------- |
+| N/A         | ![Default](../../images/hats/default.svg)       | `default`    | ✅                  |
+| `"ex"`      | ![Ex](../../images/hats/ex.svg)                 | `ex`         | ❌                  |
+| `"fox"`     | ![Fox](../../images/hats/fox.svg)               | `fox`        | ❌                  |
+| `"wing"`    | ![Wing](../../images/hats/wing.svg)             | `wing`       | ❌                  |
+| `"hole"`    | ![Hole](../../images/hats/hole.svg)             | `hole`       | ❌                  |
+| `"frame"`   | ![Frame](../../images/hats/frame.svg)           | `frame`      | ❌                  |
+| `"curve"`   | ![Curve](../../images/hats/curve.svg)           | `curve`      | ❌                  |
+| `"eye"`     | ![Eye](../../images/hats/eye.svg)               | `eye`        | ❌                  |
+| `"play"`    | ![Play](../../images/hats/play.svg)             | `play`       | ❌                  |
+| `"cross"`   | ![Crosshairs](../../images/hats/crosshairs.svg) | `crosshairs` | ❌                  |
+| `"bolt"`    | ![Bolt](../../images/hats/bolt.svg)             | `bolt`       | ❌                  |
 
 You can enable or disable shapes in your VSCode settings, by searching for `cursorless.hatEnablement.shapes` and checking the box next to the internal ID for the given shape as listed above.