Oh Canada! 🍁

.github/CONTRIBUTING.md

@@ -2,7 +2,7 @@
 
 The following is a set of guidelines for contributing to Vim for VSCode.
 These are just guidelines, not rules, use your best judgment and feel free to propose changes to this document in a pull request.
-If you need help with Vim for VSCode, come visit our [Slack](https://vscodevim-slackin.azurewebsites.net/) community.
+If you need help with Vim for VSCode, drop by on [Slack](https://vscodevim-slackin.azurewebsites.net/).
 Thanks for helping us make Vim for VSCode better!
 
 ## Submitting Issues
@@ -11,18 +11,18 @@ The [GitHub issue tracker](https://github.com/VSCodeVim/Vim/issues) is the prefe
 When creating a new bug report do:
 
 * Search against existing issues to check if somebody else has already reported your problem or requested your idea
-* Include as many details as possible. Include screenshots/gifs and repro steps where applicable.
+* Include as many details as possible -- include screenshots/gifs and repro steps where applicable.
 
 ## Submitting Pull Requests
 
 Pull requests are *awesome*.
 If you're looking to raise a PR for something which doesn't have an open issue, consider creating an issue first.
 When submitting a PR, ensure:
 
-1. Run all the tests and ensure they pass.
-2. If you added a new feature, add at least one more test to test it.
-3. If you've fixed a bug, add at least one test to ensure the bug stays away.
-4. Submit the PR. Pour yourself a glass of champagne and feel good about making contributing to open source!
+1. All tests pass.
+2. If you added a new feature, add tests to exercise the new code path.
+3. If you fixed a bug, add tests to ensure the bug stays away.
+4. Submit the PR. Pour yourself a glass of champagne and feel good about contributing to open source!
 
 ## First Time Setup
 
@@ -42,16 +42,16 @@ When submitting a PR, ensure:
 ## Developing
 
 1. Watch for changes and recompile Typescript files. Run this in the `Vim` directory: `gulp watch`
-2. Open up Visual Studio code and add the `Vim` directory as a folder.
-3. Click on the debugger. You now have two options - Launch Extension (to play around with the extension) and Launch Tests (to run the tests).
+2. Open Visual Studio Code and add the `Vim` directory as a folder.
+3. Click on the debugger. You have two options - Launch Extension (to play around with the extension) and Launch Tests (to run the tests).
 
 ## Code Architecture
 
 The code is split into two parts - ModeHandler (which is essentially the Vim state machine), and Actions (which are things that modify the state).
 
 ### Actions
 
-Actions are all currently stuffied into actions.ts (sorry!). There are:
+Actions are all currently stuffed into actions.ts (sorry!). There are:
 * BaseAction - the base Action type that all Actions derive from.
 * BaseMovement - A movement, like `w`, `h`, `{`, etc. ONLY updates the cursor position. At worst, might return an IMovement, which indicates a start and stop. This is used for movements like aw which may actually start before the cursor.
 * BaseCommand - Anything which is not just a movement is a Command. That includes motions which also update the state of Vim in some way, like `*`.
@@ -95,10 +95,10 @@ In addition to building and testing the extension, when a tag is applied to the
 
 If your autocomplete, your fuzzy file search, or your _everything_ is suddenly running slower, try to recall if you ever ran `npm test` instead of just running tests through Visual Studio Code. This will add a massive folder called `.vscode-test/` to your project, which Visual Studio Code will happily consume all of your CPU cycles indexing.
 
-Long story short, you can speed up VSC by doing this:
+Long story short, you can speed up VS Code by:
 
 `$ rm -rf .vscode-test/`
 
-## Styleguides
+## Styleguide
 
-We are adhering to VSCode's [coding guidelines](https://github.com/Microsoft/vscode/wiki/Coding-Guidelines).
+Please try your best to adhere our [style guidelines](https://github.com/VSCodeVim/Vim/blob/master/STYLE.md).

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,9 +1,9 @@
 Yay! We love PRs! 🎊
 
-Please include a description of your change & check your PR against this list, thanks:
+Please include a description of your change and ensure:
 
 - [ ] Commit message has a short title & issue references
-- [ ] Each commit does a logical chunk of work.  
-- [ ] It builds and tests pass (e.g `gulp tslint`)
+- [ ] Each commit does a logical chunk of work.
+- [ ] It builds and tests pass (e.g `gulp`)
 
-More info can be found by clicking the "guidelines for contributing" link above.
+More info can be found on our [contribution guide](https://github.com/VSCodeVim/Vim/blob/master/.github/CONTRIBUTING.md).

README.md

@@ -5,11 +5,9 @@
 
 VSCodeVim is a [Visual Studio Code](https://code.visualstudio.com/) extension that provides Vim keybindings within Visual Studio Code.
 
-Please **[report missing or buggy features on GitHub](https://github.com/VSCodeVim/Vim/issues)**.
+Please **[report missing or buggy features on GitHub](https://github.com/VSCodeVim/Vim/issues)**. We've added a lot of functionality, but everyone uses Vim in their own special way, so let us know if we're missing your favourite obscure command. :wink:
 
-We've added a lot of functionality, but everyone uses Vim in their own special way, so let us know if we're missing your favorite obscure command. :wink:
-
-We're super friendly people if you want to drop by and talk to us on our [Slack channel](https://vscodevim-slackin.azurewebsites.net)!
+We're super friendly people if you want to drop by and talk to us on [Slack](https://vscodevim-slackin.azurewebsites.net).
 
 ![Screenshot](images/screen.png)
 
@@ -30,12 +28,11 @@ See our [Github Milestone page](https://github.com/VSCodeVim/Vim/milestones) for
 
 ## Install
 
-1. Within Visual Studio Code, open the command palette (`Ctrl-Shift-P` / `Cmd-Shift-P`)
-2. Select `Install Extension` and search for 'vim' *or* run `ext install vim`
+Install the extension through the [VS Code Marketplace](https://code.visualstudio.com/docs/editor/extension-gallery).
 
 ## Configure
 
-Due to overlap between VSCode and VIm, options are loaded slightly different from native Vim. The option loading sequence/priority is
+Due to overlap between VS Code and Vim, options are loaded slightly different from native Vim. The option loading sequence is
 
 1. `:set {option}` on the fly
 2. [TODO] .vimrc.
@@ -45,7 +42,7 @@ Due to overlap between VSCode and VIm, options are loaded slightly different fro
 
 ### Supported Options
 
-Vim options can be added to your user or workspace settings (open Command Pallete and search for "User Settings" or "Workspace Settings"). Changes require restarting of VSCode to take effect.
+Vim options can be added to your user or workspace settings (open the Command Pallete and search for "User Settings" or "Workspace Settings"). Changes require restarting of VSCode to take effect.
 
 The following is a subset of the supported configurations; the full list is described in [package.json](https://github.com/VSCodeVim/Vim/blob/master/package.json#L175):
 
@@ -75,7 +72,7 @@ The following is a subset of the supported configurations; the full list is desc
 
 * insertModeKeyBindingsNonRecursive/otherModesKeyBindingsNonRecursive
   * Non-recursive keybinding overrides to use for insert and other (non-insert) modes (similar to `:noremap`)
-  * *Example:* Bind `j` to `gj`. Notice that if you attempted this binding normally, the j in gj would be expanded into gj, on and on forever. Stop this recursive expansion using insertModeKeyBindingsNonRecursive/otherModesKeyBindingNonRecursive.
+  * *Example:* Bind `j` to `gj`. Notice that if you attempted this binding normally, the j in gj would be expanded into gj, on and on forever. Stop this recursive expansion using insertModeKeyBindingsNonRecursive and/or otherModesKeyBindingNonRecursive.
 
     ```
     "vim.otherModesKeyBindingsNonRecursive": [
@@ -86,13 +83,13 @@ The following is a subset of the supported configurations; the full list is desc
     ```
 
 * useCtrlKeys
-  * Enable Vim ctrl keys thus overriding common VSCode operations (eg. copy, paste, find, etc). Setting this option to true will enable:
+  * Enable Vim ctrl keys overriding common VS Code operations (eg. copy, paste, find, etc). Setting this option to true will enable:
     * `ctrl+c`, `ctrl+[` => `<Esc>`
     * `ctrl+f` => Page Forward
     * `ctrl+v` => Visual Block Mode
     * etc.
   * Type: Boolean (Default: `false`)
-  * Example:
+  * *Example:*
 
     ```
     "vim.useCtrlKeys": true
@@ -129,20 +126,14 @@ The following is a subset of the supported configurations; the full list is desc
 On OS X, open Terminal and run the following command:
 
 ```
-defaults write com.microsoft.VSCode ApplePressAndHoldEnabled -bool false // For VSCode
-defaults write com.microsoft.VSCodeInsiders ApplePressAndHoldEnabled -bool false // For VSCode Insider
+defaults write com.microsoft.VSCode ApplePressAndHoldEnabled -bool false         // For VS Code
+defaults write com.microsoft.VSCodeInsiders ApplePressAndHoldEnabled -bool false // For VS Code Insider
 ```
 
 ## Contributing
 
-This project is maintained by a group of awesome [contributors](https://github.com/VSCodeVim/Vim/graphs/contributors) and contributions are extremely welcome :heart:. If you are having trouble thinking of how you can help, check out our [roadmap](ROADMAP.md).
-
-For a quick tutorial on how to get started, see our [contributing guide](/.github/CONTRIBUTING.md).
+This project is maintained by a group of awesome [contributors](https://github.com/VSCodeVim/Vim/graphs/contributors) and contributions are extremely welcome :heart:. If you are having trouble thinking of how you can help, check out our [roadmap](ROADMAP.md). For a quick tutorial on how to get started, see our [contributing guide](/.github/CONTRIBUTING.md).
 
 ## Changelog
 
 Please see our [list of recent releases and features added.](https://github.com/VSCodeVim/Vim/releases)
-
-## License
-
-MIT, see [License](LICENSE) for more information.

ROADMAP.md

@@ -6,7 +6,7 @@
 
 :warning: - some variations of the command are not supported
 
-:running: work in progress
+:running: - work in progress
 
 :arrow_down: - command is low priority; open an issue (or thumbs up the relevant issue) if you want to see it sooner
 

STYLE.md

@@ -1,25 +1,32 @@
 ## Style Guide
 
+In addition, to VS Code's [coding guidelines](https://github.com/Microsoft/vscode/wiki/Coding-Guidelines), please adhere to the following:
+
 * Use `for ... of` whenever possible
 
-**Rationale:** `for ... of` is awesome. It's more readable than any other variant.
+  **Rationale:** `for ... of` is awesome. It's more readable than any other variant.
 
 * Don't use `any` as much as possible
 
-**Rationale:** The language is called *Type*Script, not *Untyped*Script. :wink: Static typing is wonderful. It catches bugs and improves readability. We should strive to use it as much as possible.
+  **Rationale:** The language is called *Type*Script, not *Untyped*Script. :wink: Static typing is wonderful. It catches bugs and improves readability. We should strive to use it as much as possible.
 
 * Use `const` wherever possible.
 
-**Rationale:** Instead of reading `const` as "constant value," read it as "single assignment." Yes, it means "constant value" in other programming languages, but it's a little different in JavaScript.
+  **Rationale:** Instead of reading `const` as "constant value," read it as "single assignment." Yes, it means "constant value" in other programming languages, but it's a little different in JavaScript.
 
 * When we can't use `const`, use `let`; never `var`
 
-**Rationale:** `var` trips up programmers in a number of cases - hoisting and closure capture are two big ones. Consider the difference between
+  **Rationale:** `var` trips up programmers in a number of cases - hoisting and closure capture are two big ones. Consider the difference between
+
+  ```
+  for (var j = 0; j < 5; j++) { setTimeout(() => console.log(j), 5) }
+  ```
 
-`for (var j = 0; j < 5; j++) { setTimeout(() => console.log(j), 5) }`
+  and
 
-and
+  ```
+  for (let j = 0; j < 5; j++) { setTimeout(() => console.log(j), 5) }
+  ```
 
-`for (let j = 0; j < 5; j++) { setTimeout(() => console.log(j), 5) }`
+  Even if you're not capturing the variable, who knows if someone else might later?
 
-Even if you're not capturing the variable, who knows if someone else might later?