Update docs/hardware_keyboard_guidelines.md

[qmk_firmware.git] / docs / hardware_keyboard_guidelines.md

diff --git a/docs/hardware_keyboard_guidelines.md b/docs/hardware_keyboard_guidelines.md
index 2da4ddece90bd3fe85d7535c3084f3d25f7015d1..0026bc12b412b2eca8bc44ff922e5c33ddc6ea14 100644 (file)
--- a/docs/hardware_keyboard_guidelines.md
+++ b/docs/hardware_keyboard_guidelines.md
@@ -1,6 +1,6 @@
 # QMK Keyboard Guidelines
 
-Since starting QMK has grown by leaps and bounds thanks to people like you who contributed to creating and maintaining our community keyboards. As we have grown we have discovered some patterns that work well, and ask that you conform to them to make it easier for other people to make use of your hard work.
+Since starting, QMK has grown by leaps and bounds thanks to people like you who contribute to creating and maintaining our community keyboards. As we have grown we have discovered some patterns that work well, and ask that you conform to them to make it easier for other people to make use of your hard work.
 
 ## Naming Your Keyboard/Project
 
@@ -30,9 +30,9 @@ Clueboard uses sub-folders for both purposes, organization and keyboard revision
 
 * [`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
+    * [`clueboard`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard)  ← This is the organization directory, there's 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`
@@ -49,11 +49,11 @@ Your keyboard should be located in `qmk_firmware/keyboards/` and the directory n
 
 ### `readme.md`
 
-All projects need to have a `readme.md` file that explains what the keyboard is, who made it, where it is available, and links to more information. Please follow the [published template](documentation_templates.md#keyboard-readmemd-template).
+All projects need to have a `readme.md` file that explains what the keyboard is, who made it and where it's available. If applicable, it should also contain links to more information, such as the maker's website. Please follow the [published template](documentation_templates.md#keyboard-readmemd-template).
 
 ### `config.h`
 
-All projects need to have a `config.h` file to set things like the processor type, bootloader, USB VID/PID, and other default settings. In general you should use this file to set reasonable defaults for your keyboard that will always work.
+All projects need to have a `config.h` file that sets things like the matrix size, product name, USB VID/PID, description and other settings. In general, use this file to set essential information and defaults for your keyboard that will always work.
 
 ### `rules.mk`
 
@@ -88,7 +88,7 @@ As an example, if you have a 60% PCB that supports ANSI and ISO you might define
 
 ## Image/Hardware Files
 
-In an effort to keep the repo size down, we're no longer accepting images of any format in the repo, with few exceptions. Hosting them elsewhere (such as <https://imgurcom>) and linking them in the `readme.md` is the preferred method.
+In an effort to keep the repo size down we're no longer accepting binary files of any format, with few exceptions. Hosting them elsewhere (such as <https://imgur.com>) and linking them in the `readme.md` is preferred.
 
 Any sort of hardware file (plate, case, pcb) can't be stored in qmk_firmware, but we have the [qmk.fm repo](https://github.com/qmk/qmk.fm) where such files (as well as in-depth info) can be stored and viewed on [qmk.fm](http://qmk.fm). Downloadable files are stored in `/<keyboard>/` (name follows the same format as above) which are served at `http://qmk.fm/<keyboard>/`, and pages are generated from `/_pages/<keyboard>/` which are served at the same location (.md files are generated into .html files through Jekyll). Check out the `lets_split` directory for an example.