4 files changed, 19 insertions, 16 deletions
diff --git a/docs/faq_general.md b/docs/faq_general.md
index fcc40e0a1..7647b1c2a 100644
--- a/docs/faq_general.md
+++ b/docs/faq_general.md
@@ -10,7 +10,7 @@
 ## What Differences Are There Between QMK and TMK?
-TMK was originally designed and implemented by [Jun Wako](https://github.com/tmk). QMK started as [Jack Humbert's](https://github.com/jackhumbert) fork of TMK for the Planck. After a while Jack's fork had diverged quite a bit from TMK, and in 2015 Jack decided to rename his fork to QMK.
+TMK was originally designed and implemented by [Jun Wako](https://github.com/tmk). QMK started as [Jack Humbert](https://github.com/jackhumbert)'s fork of TMK for the Planck. After a while Jack's fork had diverged quite a bit from TMK, and in 2015 Jack decided to rename his fork to QMK.
 From a technical standpoint QMK builds upon TMK by adding several new features. Most notably QMK has expanded the number of available keycodes and uses these to implement advanced features like `S()`, `LCTL()`, and `MO()`. You can see a complete list of these keycodes in [Keycodes](keycodes.md).
diff --git a/docs/getting_started_build_tools.md b/docs/getting_started_build_tools.md
index 934617d85..88612ff56 100644
--- a/docs/getting_started_build_tools.md
+++ b/docs/getting_started_build_tools.md
@@ -1,6 +1,6 @@
 # Installing Build Tools
-This page describes setting up the build environment for QMK. These instructions cover AVR processors (such as the atmega32u4.)
+This page describes setting up the build environment for QMK. These instructions cover AVR processors (such as the atmega32u4).
 <!-- FIXME: We should have ARM instructions somewhere. -->
@@ -44,7 +44,7 @@ By default, this will download compilers for both AVR and ARM. If you don't need
    nix-shell --arg arm false
-## Mac
+## macOS
 If you're using [homebrew,](http://brew.sh/) you can use the following commands:
    brew tap osx-cross/avr
@@ -58,10 +58,10 @@ This is the recommended method. If you don't have homebrew, [install it!](http:/
 ## Windows with msys2 (recommended)
-The best environment to use, for Windows Vista through any later version (tested on 7 and 10,) is [msys2](http://www.msys2.org).
+The best environment to use, for Windows Vista through any later version (tested on 7 and 10), is [msys2](http://www.msys2.org).
-* Install msys2 by downloading and following the instructions here: http://www.msys2.org
+* Install msys2 by downloading it and following the instructions here: http://www.msys2.org
-* Open the "MSYS2 MingGW 64-bit" shortcut
+* Open the ``MSYS2 MingGW 64-bit`` shortcut
 * Navigate to your qmk checkout. For example, if it's in the root of your c drive:
 * `$ cd /c/qmk_firmware`
 * Run `util/msys2_install.sh` and follow the prompts
@@ -80,7 +80,7 @@ If you already have cloned the repository on your Windows file system you can ig
 You will need to clone the repository to your Windows file system using the normal Git for Windows and **not** the WSL Git. So if you haven't installed Git before, [download](https://git-scm.com/download/win) and install it. Then [set it up](https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup), it's important that you setup the e-mail and user name, especially if you are planning to contribute. 
-Once Git is installed, open the Git bash command and change the directory to where you want to clone QMK, note that you have to use forward slashes, and that your c drive is accessed like this `/c/path/to/where/you/want/to/go`. Then run `git clone --recurse-submodules https://github.com/qmk/qmk_firmware`, this will create a new folder `qmk_firmware` as a subfolder of the current one.
+Once Git is installed, open the Git Bash command and change the directory to where you want to clone QMK; note that you have to use forward slashes, and that your c drive is accessed like this `/c/path/to/where/you/want/to/go`. Then run `git clone --recurse-submodules https://github.com/qmk/qmk_firmware`, this will create a new folder `qmk_firmware` as a subfolder of the current one.
 ### Toolchain setup
 The Toolchain setup is done through the Windows Subsystem for Linux, and the process is fully automated. If you want to do everything manually, there are no other instructions than the scripts themselves, but you can always open issues and ask for more information.
@@ -122,8 +122,11 @@ If this is a bit complex for you, Docker might be the turn-key solution you need
 # defaults are ergodox/default
 docker run -e keymap=gwen -e keyboard=ergodox_ez --rm -v $('pwd'):/qmk:rw edasque/qmk_firmware
+```
+On Windows Docker seems to have issues with the VOLUME tag in Dockerfile, and `$('pwd')` won't print a Windows compliant path; use full path instead, like this:
-# On windows docker seems to have issue with VOLUME tag in Dockerfile, and $('pwd') won't print a windows compliant path, use full path instead like this
+```bash
 docker run -e keymap=default -e keyboard=ergobox_ez --rm -v D:/Users/Sacapuces/Documents/Repositories/qmk:/qmk:rw edasque/qmk_firmware
 ```
@@ -131,4 +134,4 @@ docker run -e keymap=default -e keyboard=ergobox_ez --rm -v D:/Users/Sacapuces/D
 This will compile the targeted keyboard/keymap and leave it in your QMK directory for you to flash.
 ## Vagrant
-If you have any problems building the firmware, you can try using a tool called Vagrant. It will set up a virtual computer with a known configuration that's ready-to-go for firmware building. OLKB does NOT host the files for this virtual computer. Details on how to set up Vagrant are in the [vagrant guide](vagrant_guide.md).
+If you have any problems building the firmware, you can try using a tool called Vagrant. It will set up a virtual computer with a known configuration that's ready-to-go for firmware building. OLKB does NOT host the files for this virtual computer. Details on how to set up Vagrant are in the [vagrant guide](getting_started_vagrant.md).
diff --git a/docs/getting_started_instroduction.md b/docs/getting_started_introduction.md
index 3cd27504d..3e9a8eb0b 100644
--- a/docs/getting_started_instroduction.md
+++ b/docs/getting_started_introduction.md
@@ -1,22 +1,22 @@
 # Introduction
-This page attempts to explain the basic information you need to know to work with the QMK project. It assumes that you are familiar with navigating a UNIX shell, but does not assume you are familiar with C or with compiling using make.
+This page attempts to explain the basic information you need to know to work with the QMK project. It assumes that you are familiar with navigating a Unix shell, but does not assume you are familiar with C or with compiling using make.
 ## Basic QMK structure
-QMK is a fork of @tmk's [tmk_keyboard](https://github.com/tmk/tmk_keyboard) project. The original TMK code, with modifications, can be found in the `tmk` folder. The QMK additions to the project may be found in the `quantum` folder. Keyboard projects may be found in the `handwired` and `keyboard` folders.
+QMK is a fork of [Jun Wako](https://github.com/tmk)'s [tmk_keyboard](https://github.com/tmk/tmk_keyboard) project. The original TMK code, with modifications, can be found in the `tmk` folder. The QMK additions to the project may be found in the `quantum` folder. Keyboard projects may be found in the `handwired` and `keyboard` folders.
 ### Keyboard project structure
-Within the `handwired` and `keyboard` folders is a directory for each keyboard project, for example `qmk_firmware/keyboards/clueboard`. Within you'll find the following structure:
+Within the folder `keyboards` and its subfolder `handwired` is a directory for each keyboard project, for example `qmk_firmware/keyboards/clueboard`. Within it you'll find the following structure:
 * `keymaps/`: Different keymaps that can be built
-* `rules.mk`: The file that sets the default "make" options. Do not edit this file directly, instead use a keymap specific `Makefile`.
+* `rules.mk`: The file that sets the default "make" options. Do not edit this file directly, instead use a keymap specific `Makefile`
 * `config.h`: The file that sets the default compile time options. Do not edit this file directly, instead use a keymap specific `config.h`.
 ### Keymap structure
-In every keymap folder, the following files may be found. Only `keymap.c` is required, if the rest of the files are not found the default options will be chosen.
+In every keymap folder, the following files may be found. Only `keymap.c` is required, and if the rest of the files are not found the default options will be chosen.
 * `config.h`: the options to configure your keymap
 * `keymap.c`: all of your keymap code, required
@@ -30,7 +30,7 @@ There are 2 `config.h` locations:
 * keyboard (`/keyboards/<keyboard>/config.h`)
 * keymap (`/keyboards/<keyboard>/keymaps/<keymap>/config.h`)
-If the keymap `config.h` exists that file is included by the build system and the keyboard `config.h` is not included. If you wish to override settings in your keymap's `config.h` you will need to include some glue code:
+If the keymap `config.h` exists, that file is included by the build system and the keyboard `config.h` is not included. If you wish to override settings in your keymap's `config.h` you will need to include some glue code:
 ```
 #ifndef CONFIG_USER_H
diff --git a/readme.md b/readme.md
index 74dd6e8a9..76acab52a 100644
--- a/readme.md
+++ b/readme.md
@@ -29,4 +29,4 @@ QMK is developed and maintained by Jack Humbert of OLKB with contributions from
 ## Documentation
-[https://docs.qmk.fm](https://docs.qmk.fm) is hosted on [Gitbook](https://www.gitbook.com/book/qmk/firmware/details) and [Github](/docs/) (they are synced). You can request changes by making a fork and [pull request](https://github.com/qmk/qmk_firmware/pulls), or by clicking the "suggest an edit" link on any page of the Docs.
+[https://docs.qmk.fm](https://docs.qmk.fm) is hosted on [Gitbook](https://www.gitbook.com/book/qmk/firmware/details) and [GitHub](/docs/) (they are synced). You can request changes by making a fork and [pull request](https://github.com/qmk/qmk_firmware/pulls), or by clicking the "suggest an edit" link on any page of the Docs.