+The names `test`, `keyboard`, and `all` are reserved for make commands and may not be used as a keyboard or subfolder name.
+
+Valid Examples:
+
+* `412_64`
+* `chimera_ortho`
+* `clueboard/66/rev3`
+* `planck`
+* `v60_type_r`
+
+## Sub-folders
+
+QMK uses sub-folders both for organization and to share code between revisions of the same keyboard. You can nest folders up to 4 levels deep:
+
+ qmk_firmware/keyboards/top_folder/sub_1/sub_2/sub_3/sub_4
+
+If a sub-folder has a `rules.mk` file it will be considered a compilable keyboard. It will be available in QMK Configurator and tested with `make all`. If you are using a folder to organize several keyboards from the same maker you should not have a `rules.mk` file.
+
+Example:
+
+Clueboard uses sub-folders for both purposes, organization and keyboard revisions.
+
+* [`qmk_firmware`](https://github.com/qmk/qmk_firmware/tree/master)
+ * [`keyboards`](https://github.com/qmk/qmk_firmware/tree/master/keyboards)
+ * [`clueboard`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard) <-- this is the organization folder, no `rules.mk` file
+ * [`60`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/60) <-- this is a compilable keyboard, it has a `rules.mk` file.
+ * [`66`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/66) <-- this is also compilable, it uses `DEFAULT_FOLDER` to specify `rev3` as the default revision
+ * [`rev1`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/66/rev1) <-- compilable, `make clueboard/66/rev1`
+ * [`rev2`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/66/rev2) <-- compilable, `make clueboard/66/rev2`
+ * [`rev3`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/66/rev3) <-- compilable, `make clueboard/66/rev3` and `make clueboard/66`
+
+## Keyboard Folder Structure
+
+Your keyboard should be located in `qmk_firmware/keyboards/` and the directory name should be your keyboard's name as described in the previous section. Inside this directory should be several files:
+
+* `readme.md`
+* `config.h`
+* `rules.mk`
+* `<keyboard_name>.c`
+* `<keyboard_name>.h`
+
+### `readme.md`