2018-05-06 19:34:47 +00:00
<!DOCTYPE html>
< html class = "no-js" lang = "en" >
< head >
< title > Documentation Best Practices - QMK Firmware< / title >
< meta name = "description" content = "Keyboard controller firmware for Atmel AVR and ARM USB families" >
< meta name = "author" content = "QMK Community" >
< meta charset = "UTF-8" >
< meta http-equiv = "X-UA-Compatible" content = "IE=edge" >
2018-05-08 04:02:24 +00:00
< link rel = "icon" href = "../themes/daux/img/favicon-navy.png" type = "image/x-icon" >
2018-05-06 19:34:47 +00:00
<!-- Mobile -->
< meta name = "apple-mobile-web-app-capable" content = "yes" / >
< meta name = "viewport" content = "width=device-width, initial-scale=1.0" >
<!-- Font -->
<!-- CSS -->
2018-05-08 04:02:24 +00:00
< link href = '../themes/daux/css/theme-navy.min.css' rel = 'stylesheet' type = 'text/css' >
2018-05-06 19:34:47 +00:00
<!-- Tipue Search -->
< link href = "../tipuesearch/tipuesearch.css" rel = "stylesheet" >
<!-- [if lt IE 9]>
< script src = "../themes/daux/js/html5shiv-3.7.3.min.js" > < / script >
<![endif]-->
< / head >
< body class = " " >
< div class = "Columns content" >
< aside class = "Columns__left Collapsible" >
< button type = "button" class = "Button Collapsible__trigger" >
< span class = "Collapsible__trigger__bar" > < / span >
< span class = "Collapsible__trigger__bar" > < / span >
< span class = "Collapsible__trigger__bar" > < / span >
< / button >
< a class = "Brand" href = "../index.html" > QMK Firmware< / a >
< div class = "Search" >
< svg class = "Search__icon" xmlns = "http://www.w3.org/2000/svg" viewBox = "0 0 451 451" >
< path d = "M447.05 428l-109.6-109.6c29.4-33.8 47.2-77.9 47.2-126.1C384.65 86.2 298.35 0 192.35 0 86.25 0 .05 86.3.05 192.3s86.3 192.3 192.3 192.3c48.2 0 92.3-17.8 126.1-47.2L428.05 447c2.6 2.6 6.1 4 9.5 4s6.9-1.3 9.5-4c5.2-5.2 5.2-13.8 0-19zM26.95 192.3c0-91.2 74.2-165.3 165.3-165.3 91.2 0 165.3 74.2 165.3 165.3s-74.1 165.4-165.3 165.4c-91.1 0-165.3-74.2-165.3-165.4z" / >
< / svg >
< input type = "search" id = "tipue_search_input" class = "Search__field" placeholder = "Search..." autocomplete = "on"
results=25 autosave=text_search>
< / div >
< div class = "Collapsible__content" >
<!-- Navigation -->
2018-05-08 04:02:24 +00:00
< ul class = 'Nav' > < li class = 'Nav__item has-children' > < a href = "../Getting_Started/index.html" class = "folder" > < i class = "Nav__arrow" > < / i > Getting Started< / a > < ul class = 'Nav' > < li class = 'Nav__item has-children' > < a href = "../Getting_Started/Install_Build_Tools/index.html" class = "folder" > < i class = "Nav__arrow" > < / i > Install Build Tools< / a > < ul class = 'Nav' > < li class = 'Nav__item ' > < a href = "../Getting_Started/Install_Build_Tools/Vagrant.html" > Vagrant< / a > < / li > < / ul > < / li > < li class = 'Nav__item ' > < a href = "../Getting_Started/Build_Compile_Instructions.html" > Build Compile Instructions< / a > < / li > < li class = 'Nav__item ' > < a href = "../Getting_Started/Flashing_Firmware.html" > Flashing Firmware< / a > < / li > < li class = 'Nav__item ' > < a href = "../Getting_Started/Contributing.html" > Contributing< / a > < / li > < li class = 'Nav__item ' > < a href = "../Getting_Started/How_to_Use_GitHub.html" > How to Use GitHub< / a > < / li > < li class = 'Nav__item ' > < a href = "../Getting_Started/Getting_Help.html" > Getting Help< / a > < / li > < / ul > < / li > < li class = 'Nav__item has-children' > < a href = "../Complete_Newbs_Guide/index.html" class = "folder" > < i class = "Nav__arrow" > < / i > Complete Newbs Guide< / a > < ul class = 'Nav' > < li class = 'Nav__item ' > < a href = "../Complete_Newbs_Guide/Complete_Newbie's_Guide.html" > Complete Newbie's Guide< / a > < / li > < li class = 'Nav__item ' > < a href = "../Complete_Newbs_Guide/Building_Your_First_Firmware.html" > Building Your First Firmware< / a > < / li > < li class = 'Nav__item ' > < a href = "../Complete_Newbs_Guide/Flashing_Firmware.html" > Flashing Firmware< / a > < / li > < li class = 'Nav__item ' > < a href = "../Complete_Newbs_Guide/Testing_and_Debugging.html" > Testing and Debugging< / a > < / li > < / ul > < / li > < li class = 'Nav__item has-children' > < a href = "../FAQ/index.html" class = "folder" > < i class = "Nav__arrow" > < / i > FAQ< / a > < ul class = 'Nav' > < li class = 'Nav__item ' > < a href = "../FAQ/General_FAQ.html" > General FAQ< / a > < / li > < li class = 'Nav__item ' > < a href = "../FAQ/Build_Compile_QMK.html" > Build Compile QMK< / a > < / li > < li class = 'Nav__item ' > < a href = "../FAQ/Debugging_and_Troubleshooting.html" > Debugging and Troubleshooting< / a > < / li > < li class = 'Nav__item ' > < a href = "../FAQ/Keymaps.html" > Keymaps< / a > < / li > < / ul > < / li > < li class = 'Nav__item has-children' > < a href = "../Hardware/index.html" class = "folder" > < i class = "Nav__arrow" > < / i > Hardware< / a > < ul class = 'Nav' > < li class = 'Nav__item ' > < a href = "../Hardware/AVR_Processors.html" > AVR Processors< / a > < / li > < li class = 'Nav__item ' > < a href = "../Hardware/Drivers.html" > Drivers< / a > < / li > < / ul > < / li > < li class = 'Nav__item has-children' > < a href = "../Features/index.html" class = "folder" > < i class = "Nav__arrow" > < / i > Features< / a > < ul class = 'Nav' > < li class = 'Nav__item ' > < a href = "../Features/Advanced_Keycodes.html" > Advanced Keycodes< / a > < / li > < li class = 'Nav__item ' > < a href = "../Features/Audio.html" > Audio< / a > < / li > < li class = 'Nav__item ' > < a href = "../Features/Auto_Shift.html" > Auto Shift< / a > < / li > < li class = 'Nav__item ' > < a href = "../Features/Backlight.html" > Backlight< / a > < / li > < li class = 'Nav__item ' > < a href = "../Features/Bluetooth.html" > Bluetooth< / a > < / li > < li class = 'Nav__item ' > < a href = "../Features/Bootmagic.html" > Bootmagic< / a > < / li > < li class = 'Nav__item ' > < a href = "../Features/Command.html" > Command< / a > < / li > < li class = 'Nav__item ' > < a href = "../Features/Dynamic_Macros.html" > Dynamic Macros< / a > < / li > < li class = 'Nav__item ' > < a href = "../Features/Grave_Escape.html" > Grave Escape< / a > < / li > < li class = 'Nav__item ' > < a href = "../Features/Key_Lock.html" > Key Lock< / a > < / li > < li class = 'Nav__item ' > < a href = "../Features/Layouts.html" > Layouts< / a > < / li > < li class = 'Nav__item ' > < a href = "../Features/Leader_Key.html" > Leader Key< / a > < / li > < li class = 'Nav__item ' > < a href = "../Features/Macros.html" > Macros< / a > < / li > < li class = 'Nav__item ' > < a href = "../Features/Mouse_Keys.html" > Mouse Keys< / a > < / li > < li class = 'Nav__item ' > < a href = "../Features/Pointing_Device.html" > Pointing Device< / a > < / li > < li class = 'Nav__item ' > < a href = "../Features/PS_2_Mouse.html" > PS 2 Mouse< / a > < / li > < li class = 'Nav__item ' > < a href = "../Features/RGB_Lighting.html" > RGB Lighting< / a > < / li > < li class = 'Nav__item ' > < a href = "../Features/Space_Cadet_Shift.html" > Space Cadet Shift< / a > < / li > < li class = 'Nav__item ' > < a href = "../Features/Space_Cad
2018-05-06 19:34:47 +00:00
< div class = "Links" >
2018-05-08 04:02:24 +00:00
< / div >
2018-05-06 19:34:47 +00:00
< / div >
< / aside >
< div class = "Columns__right Columns__right--full" >
< div class = "Columns__right__content" >
< div class = "doc_content" >
< article class = "Page" >
< div class = "Page__header" >
< h1 > < a href = "../Reference/index.html" > Reference< / a > < svg class = "Page__header--separator" xmlns = "http://www.w3.org/2000/svg" viewBox = "0 0 477.175 477.175" > < path d = "M360.73 229.075l-225.1-225.1c-5.3-5.3-13.8-5.3-19.1 0s-5.3 13.8 0 19.1l215.5 215.5-215.5 215.5c-5.3 5.3-5.3 13.8 0 19.1 2.6 2.6 6.1 4 9.5 4 3.4 0 6.9-1.3 9.5-4l225.1-225.1c5.3-5.2 5.3-13.8.1-19z" / > < / svg > < a href = "../Reference/Documentation_Best_Practices.html" > Documentation Best Practices< / a > < / h1 >
2018-05-08 04:02:24 +00:00
< span class = "EditOn" >
< a href = "https://github.com/qmk/qmk_firmware/blob/master/docs/07_Reference/Documentation_Best_Practices.md" target = "_blank" >
Edit on GitHub < / a >
< / span >
< / div >
2018-05-06 19:34:47 +00:00
< div class = "s-content" >
< ul class = "TableOfContents" >
< li >
< p > < a href = "#page_Documentation-Best-Practices" > Documentation Best Practices< / a > < / p >
< / li >
< li >
< p > < a href = "#page_Page-Opening" > Page Opening< / a > < / p >
< / li >
< li >
< p > < a href = "#page_Headings" > Headings< / a > < / p >
< / li >
< li >
< p > < a href = "#page_Styled-Hint-Blocks" > Styled Hint Blocks< / a > < / p >
< ul class = "TableOfContents" >
< li >
< p > < a href = "#page_Examples" > Examples:< / a > < / p >
< / li >
< / ul >
< / li >
< li >
< p > < a href = "#page_Styled-Terminal-Blocks" > Styled Terminal Blocks< / a > < / p >
< ul class = "TableOfContents" >
< li >
< p > < a href = "#page_Example" > Example< / a > < / p >
< / li >
< / ul >
< / li >
< li >
< p > < a href = "#page_Documenting-Features" > Documenting Features< / a > < / p >
< / li >
< / ul >
< h1 id = "page_Documentation-Best-Practices" > Documentation Best Practices< / h1 >
< p > 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.< / p >
< h1 id = "page_Page-Opening" > Page Opening< / h1 >
< p > Your documentation page should generally start with an H1 heading, followed by a 1 paragraph 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.< / p >
< p > Example:< / p >
< pre > < code > # 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.
< / code > < / pre >
< h1 id = "page_Headings" > Headings< / h1 >
< p > 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.< / p >
< h1 id = "page_Styled-Hint-Blocks" > Styled Hint Blocks< / h1 >
< p > You can have styled hint blocks drawn around text to draw attention to it.< / p >
< pre > < code > {% hint style='info' %}
This uses `hint style='info'`
{% endhint %}
< / code > < / pre >
< h3 id = "page_Examples" > Examples:< / h3 >
< p > {% hint style='info' %}
This uses < code > hint style='info'< / code >
{% endhint %}< / p >
< p > {% hint style='tip' %}
This uses < code > hint style='tip'< / code >
{% endhint %}< / p >
< p > {% hint style='danger' %}
This uses < code > hint style='danger'< / code >
{% endhint %}< / p >
< p > {% hint style='working' %}
This uses < code > hint style='working'< / code >
{% endhint %}< / p >
< h1 id = "page_Styled-Terminal-Blocks" > Styled Terminal Blocks< / h1 >
< p > You can present styled terminal blocks by including special tokens inside your text block.< / p >
< pre > < code > \`\`\`
**[terminal]
**[prompt foo@joe]**[path ~]**[delimiter $ ]**[command ./myscript]
Normal output line. Nothing special here...
But...
You can add some colors. What about a warning message?
**[warning [WARNING] The color depends on the theme. Could look normal too]
What about an error message?
**[error [ERROR] This is not the error you are looking for]
\`\`\`
< / code > < / pre >
< h3 id = "page_Example" > Example< / h3 >
< pre > < code > **[terminal]
**[prompt foo@joe]**[path ~]**[delimiter $ ]**[command ./myscript]
Normal output line. Nothing special here...
But...
You can add some colors. What about a warning message?
**[warning [WARNING] The color depends on the theme. Could look normal too]
What about an error message?
**[error [ERROR] This is not the error you are looking for]
< / code > < / pre >
< h1 id = "page_Documenting-Features" > Documenting Features< / h1 >
< p > If you create a new feature for QMK, create a documentation page for it. It doesn't have to be very long, a few sentences describing your feature and a table listing any relevant keycodes is enough. Here is a basic template:< / p >
< pre > < code class = "language-markdown" > # My Cool Feature
This page describes my cool feature. You can use my cool feature to make coffee and order cream and sugar to be delivered via drone.
## My Cool Feature Keycodes
|Long Name|Short Name|Description|
|---------|----------|-----------|
|KC_COFFEE||Make Coffee|
|KC_CREAM||Order Cream|
|KC_SUGAR||Order Sugar|
< / code > < / pre >
< p > Place your documentation into < code > docs/feature_< my_cool_feature> .md< / code > , and add that file to the appropriate place in < code > docs/_summary.md< / code > . If you have added any keycodes be sure to add them to < code > docs/06_Keycodes/index.md< / code > with a link back to your feature page.< / p >
< / div >
< nav >
< ul class = "Pager" >
< li class = Pager--prev > < a href = "../Reference/Custom_Code.html" > Previous< / a > < / li > < li class = Pager--next > < a href = "../Reference/Documentation_Templates.html" > Next< / a > < / li > < / ul >
< / nav >
< / article >
< / div >
< / div >
< / div >
< / div >
<!-- JS -->
< script src = "../themes/daux/js/jquery-1.11.3.min.js" > < / script > < script src = "../themes/daux/js/highlight.pack.js" > < / script > < script src = "../themes/daux/js/daux.js" > < / script >
<!-- Tipue Search -->
< script type = "text/javascript" src = "../tipuesearch/tipuesearch.js" > < / script >
< script >
window.onunload = function(){}; // force $(document).ready to be called on back/forward navigation in firefox
$(function() {
tipuesearch({
'base_url': '../'
});
});
< / script >
< / body >
< / html >
