From d8e29b53fe5d57f2102b77f0ce9932cdb8b021b2 Mon Sep 17 00:00:00 2001 From: skullY Date: Mon, 3 Jul 2017 01:30:36 -0700 Subject: Update a bunch of docs --- docs/documentation_best_practices.md | 39 ++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 docs/documentation_best_practices.md (limited to 'docs/documentation_best_practices.md') diff --git a/docs/documentation_best_practices.md b/docs/documentation_best_practices.md new file mode 100644 index 0000000000..1c06387f74 --- /dev/null +++ b/docs/documentation_best_practices.md @@ -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 %} -- cgit v1.2.3 From 80cc23e9128ca89340cabc3517afc440489013fe Mon Sep 17 00:00:00 2001 From: skullY Date: Mon, 3 Jul 2017 01:33:13 -0700 Subject: fix the info boxes --- docs/documentation_best_practices.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/documentation_best_practices.md') diff --git a/docs/documentation_best_practices.md b/docs/documentation_best_practices.md index 1c06387f74..5b02ac0f4a 100644 --- a/docs/documentation_best_practices.md +++ b/docs/documentation_best_practices.md @@ -23,17 +23,17 @@ Your page should generally have multiple "H1" headings. Only H1 and H2 headings You can have styled hint blocks drawn around text to draw attention to it. {% hint style='info' %} -This uses \{\% hint style='info' \%\} +This uses \{% hint style='info' %\} {% endhint %} {% hint style='tip' %} -This uses \{\% hint style='tip' \%\} +This uses \{% hint style='tip' %\} {% endhint %} {% hint style='danger' %} -This uses \{\% hint style='danger' \%\} +This uses \{% hint style='danger' %\} {% endhint %} {% hint style='working' %} -This uses \{\% hint style='working' \%\} +This uses \{% hint style='working' %\} {% endhint %} -- cgit v1.2.3 From 435f99916c92d88ef7e7541c4fda7cf6d533ec63 Mon Sep 17 00:00:00 2001 From: skullY Date: Mon, 3 Jul 2017 11:35:29 -0700 Subject: Work around quoting hell --- docs/documentation_best_practices.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/documentation_best_practices.md') diff --git a/docs/documentation_best_practices.md b/docs/documentation_best_practices.md index 5b02ac0f4a..8c5b4795a6 100644 --- a/docs/documentation_best_practices.md +++ b/docs/documentation_best_practices.md @@ -23,17 +23,17 @@ Your page should generally have multiple "H1" headings. Only H1 and H2 headings You can have styled hint blocks drawn around text to draw attention to it. {% hint style='info' %} -This uses \{% hint style='info' %\} +This uses `hint style='info'` {% endhint %} {% hint style='tip' %} -This uses \{% hint style='tip' %\} +This uses `hint style='tip'` {% endhint %} {% hint style='danger' %} -This uses \{% hint style='danger' %\} +This uses `hint style='danger'` {% endhint %} {% hint style='working' %} -This uses \{% hint style='working' %\} +This uses `hint style='working'` {% endhint %} -- cgit v1.2.3 From 4c7c7747a3a4f4abea3bdaf73e37edd42cfb6446 Mon Sep 17 00:00:00 2001 From: skullY Date: Sat, 8 Jul 2017 22:39:17 -0700 Subject: Add terminal examples to doc best practices --- docs/documentation_best_practices.md | 38 ++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) (limited to 'docs/documentation_best_practices.md') diff --git a/docs/documentation_best_practices.md b/docs/documentation_best_practices.md index 8c5b4795a6..f30793181c 100644 --- a/docs/documentation_best_practices.md +++ b/docs/documentation_best_practices.md @@ -22,6 +22,14 @@ Your page should generally have multiple "H1" headings. Only H1 and H2 headings You can have styled hint blocks drawn around text to draw attention to it. +``` +{% hint style='info' %} +This uses `hint style='info'` +{% endhint %} +``` + +### Examples: + {% hint style='info' %} This uses `hint style='info'` {% endhint %} @@ -37,3 +45,33 @@ This uses `hint style='danger'` {% hint style='working' %} This uses `hint style='working'` {% endhint %} + +# Styled Terminal Blocks + +You can present styled terminal blocks by including special tokens inside your text block. + +``` +\`\`\` +**[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] +\`\`\` +``` + +### Example + +``` +**[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] +``` -- cgit v1.2.3 From 9d1a08e38ac9937cff4e61abfd0acc26ad5fdf4a Mon Sep 17 00:00:00 2001 From: skullY Date: Sun, 6 Aug 2017 20:57:57 -0700 Subject: Doc updates from going through every file --- docs/documentation_best_practices.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) (limited to 'docs/documentation_best_practices.md') diff --git a/docs/documentation_best_practices.md b/docs/documentation_best_practices.md index f30793181c..059b25bcd3 100644 --- a/docs/documentation_best_practices.md +++ b/docs/documentation_best_practices.md @@ -75,3 +75,23 @@ You can add some colors. What about a warning message? What about an error message? **[error [ERROR] This is not the error you are looking for] ``` + +# Documenting Features + +If you create a new feature for QMK, create a documentation page for it. It doesn't have to be very long, a few sentances describing your feature and a table listing any relevant keycodes is enough. Here is a basic template: + +```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| +``` + +Place your documentation into `docs/feature_.md`, and add that file to the appropriate place in `docs/_summary.md`. If you have added any keycodes be sure to add them to `docs/keycodes.md` with a link back to your feature page. -- cgit v1.2.3