[Erez & Jack] Updates build guide

doc/BUILD_GUIDE.md

@@ -49,19 +49,19 @@ If you have any problems building the firmware, you can try using a tool called
 
 The `make` command is how you compile the firmware into a .hex file, which can be loaded by a dfu programmer (like dfu-progammer via `make dfu`) or the [Teensy loader](https://www.pjrc.com/teensy/loader.html) (only used with Teensys). You can run `make` from the root (`/`), your keyboard folder (`/keyboard/<keyboard>/`), or your keymap folder (`/keyboard/<keyboard>/keymaps/<keymap>/`) if you have a `Makefile` there (see the example [here](/doc/keymap_makefile_example.mk)).
 
-By default, this will generate a <keyboard>_<keymap>.hex file in whichever folder you run make from. These files are ignored by git, so don't worry about deleting them when committing/creating pull requests. You .hex file will also be copied into your keymap folder as `compiled.hex`, which isn't ignore by git - this is included in case first-time users are having trouble compiling, and just want to flash a layout via `make dfu-no-build`.
+By default, this will generate a `<keyboard>_<keymap>.hex` file in whichever folder you run `make` from. These files are ignored by git, so don't worry about deleting them when committing/creating pull requests. Your .hex file will also be copied into your keymap folder as `compiled.hex`, which isn't ignored by git - this is included in case first-time users are having trouble compiling, and just want to flash a layout via `make dfu-no-build` or using the Teensy loader.
 
 * The "root" (`/`) folder is the qmk_firmware folder, in which are `doc`, `keyboard`, `quantum`, etc.
-* The "keyboard" folder is any keyboard project's folder, like `/keyboard/<keyboard>`
+* The "keyboard" folder is any keyboard project's folder, like `/keyboard/planck`.
-* The "keymap" folder is any keymap's folder, like `/keyboard/<keyboard>/keymaps/<keymap>/`
+* The "keymap" folder is any keymap's folder, like `/keyboard/planck/keymaps/default`.
 
 Below is a list of the useful `make` commands in QMK:
 
 * `make` - cleans automatically and builds your keyboard and keymap depending on which folder you're in. This defaults to the "default" layout (unless in a keymap folder), and Planck keyboard in the root folder
   * `make keyboard=<keyboard>` - specifies the keyboard (only to be used in root)
   * `make keymap=<keymap>` - specifies the keymap (only to be used in root and keyboard folder - not needed when in keymap folder)
-* `make quick` - skips the clean step (only use when modifying .c code in the same project - at least one `make` is required)
+* `make quick` - skips the clean step (cannot be used immediately after modifying config.h or Makefiles)
-* `make dfu` - (requires dfu-programmer) builds and flashes the keymap to your keyboard once placed in reset/dfu mode (button or press KC_RESET).
+* `make dfu` - (requires dfu-programmer) builds and flashes the keymap to your keyboard once placed in reset/dfu mode (button or press `KC_RESET`). This does not work for Teensy-based keyboards like the ErgoDox EZ.
   * `keyboard=` and `keymap=` are compatible with this
 * `make dfu-no-build` - (requires dfu-programmer) same as `make dfu`, but doesn't build and uses the included `compiled.hex` to flash the keyboard
 * `make all-keyboards` - builds all keymaps for all keyboards and outputs status of each (use in root)
@@ -83,7 +83,7 @@ There are 3 different `make` and `Makefile` locations:
 * keyboard (`/keyboard/<keyboard>/`)
 * keymap (`/keyboard/<keyboard>/keymaps/<keymap>/`)
 
-The root contains all of the automatic keymap/keyboard stuff, is static, and shouldn't be modified. The keyboard one will contain the MCU set-up and default settings for your keyboard, and shouldn't be modified unless you are the producer of that keyboard. The keymap Makefile can be modified by users, and is optional. It is included automatically if it exists. You can see an example [here](/doc/keymap_makefile_example.mk) - the last few lines are the most important. The settings you set here will override any defaults set in the keyboard Makefile. It is required if you want to run `make` in the keymap folder.
+The root contains the code used to automatically figure out which keymap or keymaps to compile based on your current directory and commandline arguments. It's considered stable, and shouldn't be modified. The keyboard one will contain the MCU set-up and default settings for your keyboard, and shouldn't be modified unless you are the producer of that keyboard. The keymap Makefile can be modified by users, and is optional. It is included automatically if it exists. You can see an example [here](/doc/keymap_makefile_example.mk) - the last few lines are the most important. The settings you set here will override any defaults set in the keyboard Makefile. **It is required if you want to run `make` in the keymap folder.**
 
 ### The `config.h` file
 
@@ -92,16 +92,13 @@ There are 2 `config.h` locations:
 * keyboard (`/keyboard/<keyboard>/`)
 * keymap (`/keyboard/<keyboard>/keymaps/<keymap>/`)
 
-The keyboard `config.h` is included only if the keymap one doesn't exist. It's possible to included both by using this code at the top of your keymap's `config.h`:
+The keyboard `config.h` is included only if the keymap one doesn't exist. The format to use for your custom one [is here](/doc/keymap_config_h_example.h). If you want to override a setting from the parent `config.h` file, you need to do this:
 
-    #include "../../config.h"
+```
+#undef MY_SETTING
+#define MY_SETTING 4
+```c
 
-You can then overwrite any settings, rather than having to copy and paste the whole thing. You may need to `undefine` things to prevent warnings.
+For a value of `4` for this imaginary setting. So we `undef` it first, then `define` it.
 
-
+You can then override any settings, rather than having to copy and paste the whole thing.
-## Helpful Tips
-1. On Linux or OS X, you can run `sleep 5; make keymap=<keymap> dfu` to delay building/deploying the firmware until for 5 seconds, giving you a chance to put the firmware into bootloader mode. You can change the 5 to any number of seconds.
-
-## Troubleshooting
-
-	WIP

doc/keymap_config_h_example.h

@@ -0,0 +1,8 @@
+#ifndef CONFIG_USER_H
+#define CONFIG_USER_H
+
+#include "../../config.h"
+
+// place overrides here
+
+#endif