overhaul the newbs guide

docs/_summary.md

@@ -1,4 +1,4 @@
-* Complete Newbs Guide
+* Tutorial
   * [Introduction](newbs.md)
   * [Setup](newbs_getting_started.md)
   * [Building Your First Firmware](newbs_building_firmware.md)
@@ -18,10 +18,13 @@
 
 * Configurator
   * [Overview](newbs_building_firmware_configurator.md)
-  * [Keyboard Support](reference_configurator_support.md)
+  * [Step by Step](configurator_step_by_step.md)
+  * [Troubleshooting](configurator_troubleshooting.md)
+  * [Problems and Bugs](configurator_problems.md)
   * QMK API
     * [Overview](api_overview.md)
     * [API Documentation](api_docs.md)
+    * [Keyboard Support](reference_configurator_support.md)
 
 * CLI
     * [Overview](cli.md)
@@ -35,8 +38,8 @@
     * [Keymap Overview](keymap.md)
     * [Vagrant Guide](getting_started_vagrant.md)
     * Flashing
+      * [Flashing](flashing.md)
       * [Flashing ATmega32A (ps2avrgb)](flashing_bootloadhid.md)
-      * [Flashing Firmware](flashing.md)
     * Git Best Practices
       * [Introduction](newbs_git_best_practices.md)
       * [Your Fork](newbs_git_using_your_master_branch.md)
@@ -53,7 +56,6 @@
     * [Quantum Keycodes](quantum_keycodes.md)
 
   * Advanced Keycodes
-    * [Auto Shift](feature_auto_shift.md)
     * [Command](feature_command.md)
     * [Dynamic Macros](feature_dynamic_macros.md)
     * [Grave Escape](feature_grave_esc.md)
@@ -64,6 +66,7 @@
     * [US ANSI Shifted Keys](keycodes_us_ansi_shifted.md)
 
   * Software Features
+    * [Auto Shift](feature_auto_shift.md)
     * [Combos](feature_combo.md)
     * [Debounce API](feature_debounce_type.md)
     * [Key Lock](feature_key_lock.md)

docs/configurator_problems.md

@@ -0,0 +1,3 @@
+# Problems and Bugs
+
+We are always accepting customer requests and bug reports. Please file them at [qmk_configurator](https://github.com/qmk/qmk_configurator/issues)

docs/configurator_step_by_step.md

@@ -0,0 +1,58 @@
+# Step by Step
+
+This page describes the steps for building your firmware in QMK Configurator.
+
+## Step 1: Select your keyboard
+
+Click the drop down box and select the keyboard you want to create a keymap for.
+
+?> If your keyboard has several versions, make sure you select the correct one.
+
+I'll say that again because it's important:
+
+!> **MAKE SURE YOU SELECT THE RIGHT VERSION!**
+
+If your keyboard has been advertised to be powered by QMK but is not in the list, chances are a developer hasn't gotten to it yet or we haven't had a chance to merge it in yet. File an issue at [qmk_firmware](https://github.com/qmk/qmk_firmware/issues) requesting to support that particular keyboard, if there is no active [Pull Request](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+is%3Apr+label%3Akeyboard) for it. There are also QMK powered keyboards that are in their manufacturer's own github accounts. Double check for that as well.  <!-- FIXME(skullydazed): This feels too wordy and I'm not sure we want to encourage these kinds of issues. Also, should we prompt them to bug the manufacutrer? -->
+
+## Step 2: Select your keyboard layout
+
+Choose the layout that best represents the keymap you want to create. Some keyboards do not have enough layouts or correct layouts defined yet. They will be supported in the future.
+
+!> Sometimes there isn't a layout that supports your exact build. In that case select `LAYOUT_all`.
+
+## Step 3: Name Your Keymap
+
+Call this keymap what you want.
+
+?> If you are running into issues when compiling, it may be worth changing this name, as it may already exist in the QMK Firmware repo.
+
+## Step 4: Define Your Keymap
+
+Keycode Entry is accomplished in one of 3 ways.
+
+1. Drag and drop
+2. Clicking on an empty spot on the layout and clicking the keycode you desire
+3. Clicking on an empty spot on the layout, pressing the physical key on your keyboard.
+
+?> Hover your mouse over a key and a short blurb will tell you what that keycode does. For a more verbose description please see:
+
+* [Basic Keycode Reference](keycodes_basic.md)
+* [Advanced Keycode Reference](feature_advanced_keycodes.md)
+
+!> If your selected layout doesn't match your physical build leave the unused keys blank. If you're not sure which key is in use, for example you have a one backspace key but `LAYOUT_all` has 2 keys, put the same keycode in both locations.
+
+## Step 5: Save Your Keymap for Future Changes
+
+When you're satisfied with your keymap or just want to work on it later, press the `Export Keymap` button. It will save your keymap to your computer. You can then load this .json file in the future by pressing the `Import Keymap` button.
+
+!> **CAUTION:** This is not the same type of .json file used for kbfirmware.com or any other tool. If you try to use this for those tools, or the .json from those tools with QMK Configurator, you will encounter problems.
+
+## Step 6: Compile your firmware file
+
+Press the green `Compile` button.
+
+When the compilation is done, you will be able to press the green `Download Firmware` button.
+
+## Next steps: Flashing Your Keyboard
+
+Please refer to [Flashing Firmware](newbs_flashing.md)

docs/configurator_troubleshooting.md

@@ -0,0 +1,22 @@
+# Configurator Troubleshooting
+
+## My .json file is not working
+
+If the .json file was generated with QMK Configurator, congratulations you have stumbled upon a bug. File an issue at [qmk_configurator](https://github.com/qmk/qmk_configurator/issues)
+
+If not....how did you miss my big bold message at the top saying not to use other .json files?
+
+## There are extra spaces in my layout? What do I do?
+
+If you're referring to having three spots for space bar, the best course of action is to just fill them all with space bar. The same can be done for backspace and shifts
+
+## What is the keycode for.......
+
+Please see:
+
+* [Basic Keycode Reference](keycodes_basic.md)
+* [Advanced Keycode Reference](feature_advanced_keycodes.md)
+
+## It won't compile
+
+Please double check the other layers of your keymap to make sure there are no random keys present.

docs/es/newbs_building_firmware_configurator.md

@@ -4,7 +4,7 @@ El [Configurador QMK](https://config.qmk.fm) es un entorno gráfico online que g
 
 ?> **Por favor sigue estos pasos en orden.**
 
-Ve el [Video tutorial](https://youtu.be/tx54jkRC9ZY)
+Ve el [Video tutorial](https://www.youtube.com/watch?v=-imgglzDMdY)
 
 El Configurador QMK functiona mejor con Chrome/Firefox. 
 

docs/fr-fr/newbs_building_firmware_configurator.md

@@ -4,7 +4,7 @@ Le [Configurateur de QMK](https://config.qmk.fm) est une interface graphique en
 
 ?> **S'il vous plaît, suivez les étapes suivantes dans l'ordre.**
 
-Regardez le [Tutoriel vidéo](https://youtu.be/tx54jkRC9ZY)
+Regardez le [Tutoriel vidéo](https://youtu.be/tx54jkRC9ZY)https://www.youtube.com/watch?v=-imgglzDMdY)
 
 Le configurateur de QMK fonctionne mieux avec Chrome et Firefox.
 

docs/ja/newbs_building_firmware_configurator.md

@@ -10,7 +10,7 @@
 
 ?> **次の手順を順番に実行してください。**
 
-[Video Tutorial](https://youtu.be/tx54jkRC9ZY) を見てください。
+[Video Tutorial](https://www.youtube.com/watch?v=-imgglzDMdY) を見てください。
 
 QMK Configurator は Chrome/Firefox で最適に動作します。
 

docs/newbs.md

@@ -1,6 +1,8 @@
 # The Complete Newbs Guide To QMK
 
-QMK is a powerful Open Source firmware for your mechanical keyboard. You can use QMK to customize your keyboard in ways both simple and powerful. People of all skill levels, from complete newbie to master programmer, have successfully used QMK to customize their keyboard. This guide will help you do the same, no matter your skill level.
+Your computer keyboard has a processor inside of it, similar to the one inside your computer. This processor runs software that is responsible for detecting button presses and informing the computer when keys are pressed. QMK Firmware fills the role of that software, detecting button presses and passing that information on to the host computer. When you build your custom keymap, you are creating an executable program for your keyboard.
+
+QMK tries to put a lot of power into your hands by making easy things easy, and hard things possible. You don't have to know how to program to create powerful keymaps — you only have to follow a few simple syntax rules.
 
 Not sure if your keyboard can run QMK? If it's a mechanical keyboard you built yourself chances are good it can. We support a [large number of hobbyist boards](http://qmk.fm/keyboards/). If your current keyboard can't run QMK there are a lot of choices out there for boards that do.
 
@@ -10,17 +12,19 @@ This guide is suitable for everyone who wants to build a keyboard firmware using
 
 ## Overview
 
-There are 6 main sections to this guide:
+There are 4 main sections to this guide:
 
-1. [Getting Started](newbs_getting_started.md)
+1. [Setup Your Environment](newbs_getting_started.md)
 2. [Building Your First Firmware](newbs_building_firmware.md)
 3. [Flashing Firmware](newbs_flashing.md)
 4. [Testing and Debugging](newbs_testing_debugging.md)
-5. [Best Git Practices](newbs_git_best_practices.md)
-6. [Learn More with these Resources](newbs_learn_more_resources.md)
 
 This guide is focused on helping someone who has never compiled software before. It makes choices and recommendations based on that viewpoint. There are alternative methods for many of these procedures, and we support most of those alternatives. If you have any doubt about how to accomplish a task you can [ask us for guidance](getting_started_getting_help.md).
 
 ## Additional Resources
 
-* [Thomas Baart's QMK Basics Blog](https://thomasbaart.nl/category/mechanical-keyboards/firmware/qmk/qmk-basics/) – A user-created blog covering the basics of how to use QMK Firmware, as seen from a new user's perspective.
+Beyond this guide there are several resources you may find helpful while you learn QMK. We've collected them on the [Learning Resources](newbs_learn_more_resources.md) page.
+
+## Open Source
+
+QMK is Open Source Software released under the GNU General Public License.

docs/newbs_building_firmware.md

@@ -30,11 +30,12 @@ This line indicates where the list of Layers begins. Below that you'll find line
 
 ## Customize The Layout To Your Liking
 
-How to complete this step is entirely up to you. Make the one change that's been bugging you, or completely rework everything. You can remove layers if you don't need all of them, or add layers up to a total of 32. Check the following documentation to find out what you can define here:
+How to complete this step is entirely up to you. Make the one change that's been bugging you, or completely rework everything. You can remove layers if you don't need all of them, or add layers up to a total of 32. There are a lot of features in QMK, explore the sidebar to the left under "Using QMK" to see the full list. To get you started here are a few of the easier to use features:
 
-* [Keycodes](keycodes.md)
+* [Basic Keycodes](keycodes_basic.md)
-* [Features](features.md)
+* [Quantum Keycodes](quantum_keycodes.md)
-* [FAQ](faq.md)
+* [Grave/Escape](feature_grave_esc.md)
+* [Mouse keys](feature_mouse_keys.md)
 
 ?> While you get a feel for how keymaps work, keep each change small. Bigger changes make it harder to debug any problems that arise.
 

docs/newbs_building_firmware_configurator.md

@@ -1,105 +1,11 @@
 # QMK Configurator
 
+[![QMK Configurator Screenshot](https://i.imgur.com/anw9cOL.png)](https://config.qmk.fm/)
+
 The [QMK Configurator](https://config.qmk.fm) is an online graphical user interface that generates QMK Firmware hex files.
 
-?> **Please follow these steps in order.**
+Watch the [Video Tutorial](https://www.youtube.com/watch?v=-imgglzDMdY). Many people find that is enough information to start programming their own keyboard.
 
-Watch the [Video Tutorial](https://youtu.be/tx54jkRC9ZY)
+The QMK Configurator works best with Chrome or Firefox.
 
-The QMK Configurator works best with Chrome/Firefox.
+!> **Note: Files from other tools such as KLE, or kbfirmware will not be compatible with QMK Configurator. Do not load them, do not import them. QMK Configurator is a DIFFERENT tool.**
-
-
-!> **Files from other tools such as KLE, or kbfirmware will not be compatible with QMK Configurator. Do not load them, do not import them. QMK Configurator is a DIFFERENT tool.**
-
-## Selecting your keyboard
-
-Click the drop down box and select the keyboard you want to create a keymap for.
-
-?> If your keyboard has several versions, make sure you select the correct one.
-
-I'll say that again because it's important:
-
-!> **MAKE SURE YOU SELECT THE RIGHT VERSION!**
-
-If your keyboard has been advertised to be powered by QMK but is not in the list, chances are a developer hasn't gotten to it yet or we haven't had a chance to merge it in yet. File an issue at [qmk_firmware](https://github.com/qmk/qmk_firmware/issues) requesting to support that particular keyboard, if there is no active [Pull Request](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+is%3Apr+label%3Akeyboard) for it. There are also QMK powered keyboards that are in their manufacturer's own github accounts. Double check for that as well.
-
-## Selecting your keyboard layout
-
-Choose the layout that best represents the keymap you want to create. Some keyboards do not have enough layouts or correct layouts defined yet. They will be supported in the future.
-
-## Keymap Name
-
-Call this keymap what you want.
-
-?> If you are running into issues when compiling, it may be worth changing this name, as it may already exist in the QMK  Firmware repo.
-
-## Creating Your Keymap
-
-Keycode Entry is accomplished in 3 ways.
-1. Drag and dropping
-2. Clicking on an empty spot on the layout and clicking the keycode you desire
-3. Clicking on an empty spot on the layout, pressing the physical key on your keyboard.
-
-Hover your mouse over a key and a short blurb will tell you what that keycode does. For a more verbose description please see:
-
-* [Basic Keycode Reference](keycodes_basic.md)
-* [Advanced Keycode Reference](feature_advanced_keycodes.md)
-
-In the event that you can't find a layout that supports your keymap, for example three spots for spacebar, or two spots for backspace, or 2 spots for shift etc etc, Fill them ALL up.
-
-### Example:
-
-3 spots for spacebar: Fill them ALL with spacebar
-
-2 spots for backspace: Fill them BOTH with backspace
-
-2 spots for right shift: Fill them BOTH with right shift
-
-1 spot for left shift and 1 spot for iso support: Fill them both with left shift
-
-5 spots, but only 4 keys: Guess and check or ask someone who has done it before.
-
-## Saving Your Keymap for Future Edits
-
-When you're satisfied with your keymap or just want to work on it later, press the `Export Keymap` button. It will save your keymap as the name you chose above appended with .json.
-
-You can then load this .json file in the future by pressing the `Import Keymap` button.
-
-!> **CAUTION:** This is not the same type of .json file used for kbfirmware.com or any other tool. If you try to use this for those tools, or the .json from those tools with QMK Configurator, there is a chance your keyboard will **explode**.
-
-## Generating your firmware file
-
-Press the green `Compile` button.
-
-When the compilation is done, you will be able to press the green `Download Firmware` button.
-
-## Flashing Your Keyboard
-
-Please refer to [Flashing Firmware](newbs_flashing.md)
-
-## Troubleshooting
-
-#### My .json file is not working
-
-If the .json file was generated with QMK Configurator, congratulations you have stumbled upon a bug. File an issue at [qmk_configurator](https://github.com/qmk/qmk_configurator/issues)
-
-If not....how did you miss my big bold message at the top saying not to use other .json files?
-
-#### There are extra spaces in my layout? What do I do?
-
-If you're referring to having three spots for space bar, the best course of action is to just fill them all with space bar. The same can be done for backspace and shifts
-
-#### What is the keycode for.......
-
-Please see:
-
-* [Basic Keycode Reference](keycodes_basic.md)
-* [Advanced Keycode Reference](feature_advanced_keycodes.md)
-
-#### It won't compile
-
-Please double check the other layers of your keymap to make sure there are no random keys present.
-
-## Problems and Bugs
-
-We are always accepting customer requests and bug reports. Please file them at [qmk_configurator](https://github.com/qmk/qmk_configurator/issues)

docs/newbs_flashing.md

@@ -6,7 +6,7 @@ Now that you've built a custom firmware file you'll want to flash your keyboard.
 
 The simplest way to flash your keyboard will be with the [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases). 
 
-However, the QMK Toolbox is only available for Windows and macOS currently.  If you're using Linux (or just wish to flash the firmware from the command line), you'll have to use the [method outlined below](newbs_flashing.md#flash-your-keyboard-from-the-command-line).
+However, the QMK Toolbox is only available for Windows and macOS currently.  If you're using Linux (or just wish to flash the firmware from the command line), proceed down to [Flash Your Keyboard From The Command Line](newbs_flashing.md#flash-your-keyboard-from-the-command-line).
 
 ### Load The File Into QMK Toolbox
 
@@ -100,26 +100,10 @@ However, this does rely on the bootloader being set by the keyboard.  If this in
 
     WARNING: This board's bootloader is not specified or is not supported by the ":flash" target at this time.
 
-In this case, you'll have to fall back on specifying the bootloader.
+In this case, you'll have to fall back on specifying the bootloader. See the [Flashing Firmware](flashing.md) Guide for more details.
-
-There are five main bootloaders that are used. Pro Micro and clones use Caterina, Teensys use HalfKay, OLKB's AVR boards use QMK-DFU, other ATmega32U4 boards use DFU, and most ARM boards use ARM DFU.
-
-You can find more information about the bootloaders in the [Flashing Instructions and Bootloader Information](flashing.md) page. 
-
-If you know what bootloader that you're using you can specify that in your flash command:
-
-    qmk flash -bl <bootloader>
-
-Run this command to get a list of valid bootloaders:
-
-    qmk flash --bootloaders
-
-### More information
-
-See the Flashing documentation for more information on esoteric flashing situations.
 
 ## Test It Out!
 
 Congrats! Your custom firmware has been programmed to your keyboard!
 
-Give it a try and make sure everything works the way you want it to. We've written [Testing and Debugging](newbs_testing_debugging.md) to round out this Newbie Guide, so head over there to learn about validating your firmware and how to troubleshoot your custom functionality.
+Give it a try and make sure everything works the way you want it to. We've written [Testing and Debugging](newbs_testing_debugging.md) to round out this guide, so head over there to learn about validating your firmware and how to troubleshoot your custom functionality.

docs/newbs_getting_started.md

@@ -1,16 +1,10 @@
-# Getting Started
+# Setting Up Your QMK Environment
-
-Your computer keyboard has a processor inside of it, similar to the one inside your computer. This processor runs software that is responsible for detecting button presses and informing the computer when keys are pressed. QMK fills the role of that software, detecting button presses and passing that information on to the host computer. When you build your custom keymap, you are creating an executable program for your keyboard.
-
-QMK tries to put a lot of power into your hands by making easy things easy, and hard things possible. You don't have to know how to program to create powerful keymaps — you only have to follow a few simple syntax rules.
-
-# Prerequisites
 
 Before you can build keymaps, you need to install some software and set up your build environment. This only has to be done once no matter how many keyboards you plan to compile firmware for.
 
-If you would prefer a more graphical user interface approach, please consider using the online [QMK Configurator](newbs_building_firmware_configurator.md).
+## 1. Download Software
 
-## Download Software
+There are a few pieces of software you'll need to get started.
 
 ### Text Editor
 
@@ -29,7 +23,13 @@ QMK Toolbox is an optional graphical program for Windows and macOS that allows y
 * For Windows: `qmk_toolbox.exe` (portable) or `qmk_toolbox_install.exe` (installer)
 * For macOS: `QMK.Toolbox.app.zip` (portable) or `QMK.Toolbox.pkg` (installer)
 
-## Set Up Your Environment
+### A Unix-like Environment
+
+Linux and macOS come with unix shells you can execute already. You will only need to setup your build environment.
+
+On Windows you will need to install MSYS2 or WSL and use those environments. Instructions for setting up MSYS2 are provided below.
+
+## Prepare Your Build Environment
 
 We've tried to make QMK as easy to set up as possible. You only have to prepare your Linux or Unix environment, then let QMK install the rest.
 
@@ -48,7 +48,6 @@ After opening a new MSYS2 MinGW 64-bit terminal run these commands:
 
     pacman -S git python3-pip
     python3 -m pip install qmk
-    qmk setup
 
 ### macOS
 
@@ -58,7 +57,6 @@ After Homebrew is installed run these commands:
 
     brew tap qmk/qmk
     brew install qmk
-    qmk setup
 
 ### Linux
 
@@ -68,13 +66,17 @@ You will need to install Git and Python. It's very likely that you already have
 * Fedora / Red Hat / CentOS: `yum install git python3 && python3 -m pip install qmk`
 * Arch: `pacman -S qmk`
 
+## 2. Run QMK Setup
+
 After installing QMK you can set it up with this command:
 
     qmk setup
 
+In most situations you will want to answer Yes to all of the prompts.
+
 ?> If you already know [how to use GitHub](getting_started_github.md), we recommend that you create your own fork and use `qmk setup <github_username>` to clone your personal fork. If you don't know what that means you can safely ignore this message.
 
-## Test Your Build Environment
+## 3. Test Your Build Environment
 
 Now that your QMK build environment is set up, you can build a firmware for your keyboard. Start by trying to build the keyboard's default keymap. You should be able to do that with a command in this format:
 
@@ -94,7 +96,7 @@ Checking file size of clueboard_66_rev3_default.hex
  * The firmware size is fine - 26356/28672 (2316 bytes free)
 ```
 
-## Configure Your Build Environment
+## 4. Configure Your Build Environment (Optional)
 
 You can configure your build environment to set the defaults and make working with QMK less tedious. Let's do that now!
 
@@ -106,6 +108,10 @@ You can also set your default keymap name. Most people use their github username
 
     qmk config user.keymap=<github_username>
 
+After this you can leave those arguments off and compile your keyboard like this:
+
+    qmk compile
+
 # Creating Your Keymap
 
 You are now ready to create your own personal keymap! Move on to [Building Your First Firmware](newbs_building_firmware.md) for that.

docs/newbs_learn_more_resources.md

@@ -2,11 +2,15 @@
 
 These resources are aimed at giving new members in the QMK community more understanding to the information provided in the Newbs docs.
 
-Command Line resources:
+**QMK resources**:
+
+* [Thomas Baart's QMK Basics Blog](https://thomasbaart.nl/category/mechanical-keyboards/firmware/qmk/qmk-basics/) – A user-created blog covering the basics of how to use QMK Firmware, as seen from a new user's perspective.
+
+**Command Line resources**:
 
 * [Good General Tutorial on Command Line](https://www.codecademy.com/learn/learn-the-command-line)
 
-Git resources:
+**Git resources**:
 
 * [Great General Tutorial](https://www.codecademy.com/learn/learn-git)
 * [Flight Rules For Git](https://github.com/k88hudson/git-flight-rules)

docs/newbs_testing_debugging.md

@@ -20,6 +20,10 @@ void keyboard_post_init_user(void) {
 }
 ```
 
+## Debugging Tools
+
+There are two different tools you can use to debug your keyboard.
+
 ### Debugging With QMK Toolbox
 
 For compatible platforms, [QMK Toolbox](https://github.com/qmk/qmk_toolbox) can be used to display debug messages from your keyboard.
@@ -28,8 +32,6 @@ For compatible platforms, [QMK Toolbox](https://github.com/qmk/qmk_toolbox) can
 
 Prefer a terminal based solution? [hid_listen](https://www.pjrc.com/teensy/hid_listen.html), provided by PJRC, can also be used to display debug messages. Prebuilt binaries for Windows,Linux,and MacOS are available.
 
-<!-- FIXME: Describe the debugging messages here. -->
-
 ## Sending Your Own Debug Messages
 
 Sometimes it's useful to print debug messages from within your [custom code](custom_quantum_functions.md). Doing so is pretty simple. Start by including `print.h` at the top of your file: