From d8e29b53fe5d57f2102b77f0ce9932cdb8b021b2 Mon Sep 17 00:00:00 2001
From: skullY <skullydazed@gmail.com>
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 <skullydazed@gmail.com>
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 <skullydazed@gmail.com>
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