Update a bunch of docs
skullY
7 years ago
parent
ea8df568f2
commit
d8e29b53fe
@ -1,7 +1,16 @@
|
||||
If you have an idea for a custom feature or extra hardware connection, we'd love to accept it into QMK! These are generally done via [pull request](https://github.com/qmk/qmk_firmware/pulls) after forking, and here are some things to keep in mind when creating one:
|
||||
# How To Add Features To QMK
|
||||
|
||||
* **Disable by default** - memory is a pretty limited on most chips QMK supports, and it's important that current keymaps aren't broken, so please allow your feature to be turned **on**, rather than being turned off. If you think it should be on by default, or reduces the size of the code, [open an issue](https://github.com/qmk/qmk_firmware/issues) for everyone to discuss it!
|
||||
If you have an idea for a custom feature or extra hardware connection, we'd love to accept it into QMK!
|
||||
|
||||
Before you put a lot of work into building your new feature you should make sure you are implementing it in the best way. You can get a basic understanding of QMK by reading [Understaning QMK](understanding_qmk.html), which will take you on a tour of the QMK program flow. From here you should talk to us to get a sense of the best way to implement your idea. There are two main ways to do this:
|
||||
|
||||
* [Chat on Gitter](https://gitter.im/qmk/qmk_firmware)
|
||||
* [Open an Issue](https://github.com/qmk/qmk_firmware/issues/new)
|
||||
|
||||
Once you have implemented your new feature you will generally submit a [pull request](https://github.com/qmk/qmk_firmware/pulls). Here are some things to keep in mind when creating one:
|
||||
|
||||
* **Disabled by default** - memory is a pretty limited on most chips QMK supports, and it's important that current keymaps aren't broken, so please allow your feature to be turned **on**, rather than being turned off. If you think it should be on by default, or reduces the size of the code, please talk with us about it.
|
||||
* **Compile locally before submitting** - hopefully this one is obvious, but things need to compile! Our Travis system will catch any issues, but it's generally faster for you to compile a few keyboards locally instead of waiting for the results to come back.
|
||||
* **Consider subprojects and different chip-bases** - there are several keyboards that have subprojects that have allow for slightly different configurations, and even different chip-bases. Try to make a feature supported in ARM and AVR, or automatically disabled in one that doesn't work.
|
||||
* **Explain your feature** - submitting a markdown write-up of what your feature does with your PR may be needed, and it will allow a collaborator to easily copy it into the wiki for documentation (after proofing and editing).
|
||||
* **Don't refactor code** - to maintain a clear vision of how things are laid out in QMK, we try to plan out refactors in-depth, and have a collaborator make the changes. If you have an idea for refactoring, or suggestions, [open an issue](https://github.com/qmk/qmk_firmware/issues).
|
||||
* **Explain your feature** - Document it in `docs/`, either as a new file or as part of an existing file. If you don't document it other people won't be able to benefit from your hard work.
|
||||
* **Don't refactor code** - to maintain a clear vision of how things are laid out in QMK, we try to plan out refactors in-depth, and have a collaborator make the changes. If you have an idea for refactoring, or suggestions, [open an issue](https://github.com/qmk/qmk_firmware/issues).
|
||||
|
||||
@ -1,7 +0,0 @@
|
||||
Understanding the essential changes made on the [tmk_keyboard firmware](http://github.com/tmk/tmk_keyboard) should help you understand the QMK Firmware.
|
||||
|
||||
| Firmware |TMK |QMK |
|
||||
|------------------------------|-----------------------|-------------------------|
|
||||
| Maintainer |hasu (@tmk) |Jack Humbert et al. |
|
||||
| Build path customization | `TMK_DIR = ...` | `include .../Makefile` |
|
||||
| `keymaps` array data | 3D array of `uint8_t` holding **keycode** | 3D array of `uint16_t` holding **keycode** |
|
||||
@ -0,0 +1,39 @@
|
||||
# Documentation Best Practices
|
||||
|
||||
This page exists to document best practices when writing documentation for QMK. Following these guidelines will help to keep a consistent tone and style, which will in turn help other people more easily understand QMK.
|
||||
|
||||
# Page Opening
|
||||
|
||||
Your documentation page should generally start with an H1 heading, followed by a 1 paragrah description of what the user will find on this page. Keep in mind that this heading and paragraph will sit next to the Table of Contents, so keep the heading short and avoid long strings with no whitespace.
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
# My Page Title
|
||||
|
||||
This page covers my super cool feature. You can use this feature to make coffee, squeeze fresh oj, and have an egg mcmuffin and hashbrowns delivered from your local macca's by drone.
|
||||
```
|
||||
|
||||
# Headings
|
||||
|
||||
Your page should generally have multiple "H1" headings. Only H1 and H2 headings will included in the Table of Contents, so plan them out appropriately. Excess width should be avoided in H1 and H2 headings to prevent the Table of Contents from getting too wide.
|
||||
|
||||
# Styled Hint Blocks
|
||||
|
||||
You can have styled hint blocks drawn around text to draw attention to it.
|
||||
|
||||
{% hint style='info' %}
|
||||
This uses \{\% hint style='info' \%\}
|
||||
{% endhint %}
|
||||
|
||||
{% hint style='tip' %}
|
||||
This uses \{\% hint style='tip' \%\}
|
||||
{% endhint %}
|
||||
|
||||
{% hint style='danger' %}
|
||||
This uses \{\% hint style='danger' \%\}
|
||||
{% endhint %}
|
||||
|
||||
{% hint style='working' %}
|
||||
This uses \{\% hint style='working' \%\}
|
||||
{% endhint %}
|
||||
@ -1,10 +1,29 @@
|
||||
# Glossary of QMK terms
|
||||
|
||||
git
|
||||
: versioning software used at the commandline
|
||||
## Dynamic Macro
|
||||
A macro which has been recorded on the keyboard and which will be lost when the keyboard is unplugged or the computer rebooted.
|
||||
|
||||
keymap
|
||||
: an array of keycodes mapped to a physical keyboard layout, which are processed on key presses and releases
|
||||
## git
|
||||
Versioning software used at the commandline
|
||||
|
||||
matrix
|
||||
: a wiring pattern of columns and rows (and usually diodes) that enables the MCU to detect keypresses with a fewer number of pins
|
||||
## Keycode
|
||||
A 2-byte number that represents a particular key. `0x00`-`0xFF` are used for [Basic Keycodes](keycodes.html) while `0x100`-`0xFFFF` are used for [Quantum Keycodes](quantum_keycodes.html).
|
||||
|
||||
## Keymap
|
||||
An array of keycodes mapped to a physical keyboard layout, which are processed on key presses and releases
|
||||
|
||||
## Matrix
|
||||
A wiring pattern of columns and rows (and usually diodes) that enables the MCU to detect keypresses with a fewer number of pins
|
||||
|
||||
## Macro
|
||||
A feature that lets you send muiltple keypress events (hid reports) after having pressed only a single key.
|
||||
|
||||
## Mousekeys
|
||||
A feature that lets you control your mouse cursor and click from your keyboard.
|
||||
|
||||
* [Mousekeys Documentation](mouse_keys.html)
|
||||
|
||||
## Tap Dance
|
||||
A feature that lets you assign muiltple keycodes to the same key based on how many times you press it.
|
||||
|
||||
* [Tap Dance Documentation](tap_dance.html)
|
||||
|
||||
Loading…
Reference in New Issue