From 0a0ab2b46b1757f3306ba0902cd027969027f16e Mon Sep 17 00:00:00 2001
From: Sean Madsen <sean@seanmadsen.com>
Date: Sat, 7 Jan 2017 16:48:10 -0700
Subject: [PATCH] Moving "content standards" that Sean proposed in
Documentation page into the new Style Guide page
---
.../documentation-style-guide.md | 18 ++++++++++----
docs/documentation.md | 24 -------------------
2 files changed, 14 insertions(+), 28 deletions(-)
diff --git a/docs/best-practices/documentation-style-guide.md b/docs/best-practices/documentation-style-guide.md
index 22c4b82f..d43d7f70 100644
--- a/docs/best-practices/documentation-style-guide.md
+++ b/docs/best-practices/documentation-style-guide.md
@@ -14,8 +14,16 @@ Similar to most text books and manuals, we divide our guides into "parts",
- "chapter" - file (in markdown), also one web page with a given URL
- "section" - heading within the page
-Keep the page hierarchy to this depth (i.e. do not put folders within other
-folders).
+In the navigation menu: (as stored in `mkdocs.yml`)
+
+- Keep the page hierarchy to this depth (i.e. do not put folders within other
+ folders).
+- Each chapter name should be short enough to fit nicely in the menu,
+ but also long enough to stand on its own to a reasonable extent.
+ The titles set here are used in the navigation menu *and* the page title
+ that displays in the browser tab. The guide will be more usable if the
+ reader sees two tabs titled "Using Hooks" and "API Usage" instead of
+ "Usage" and "Usage".
Each chapter should start with a paragraph that explains what will be
covered in the chapter.
@@ -31,8 +39,10 @@ in H2 and H3, only where necessary. If you find yourself wanting to use
H4, consider if it's truly necessary and whether the chapter should
instead be refactored.
-Part titles and subheadings should be in sentence case (first word
-capitalized), not headline case (each word capitalized).
+### Capitalization
+
+Titles for parts, chapters, and sections should all be in sentence case
+(first word capitalized), not headline case (each word capitalized).
## Formatting conventions
diff --git a/docs/documentation.md b/docs/documentation.md
index 88e58fcb..e6c89c88 100644
--- a/docs/documentation.md
+++ b/docs/documentation.md
@@ -61,28 +61,4 @@ However, for a better editing experience we highly recommend installing
1. When you are happy with your edits, use git to commit and push your changes.
Then submit a pull request on GitHub.
-### Content standards for guides
-
-These content standards apply to all guides written in MkDocs.
-
-- Keep it simple
- - Be concise.
- - When possible, avoid the use of: tables, deeply nested lists, and
- images.
-- Page titles
- - *In navigation menu:* (as stored in `mkdocs.yml`) should be short enough
- to fit nicely in the menu, but should also long enough to stand on its
- own to a reasonable extent. The titles set here are used in the
- navigation menu *and* the page title that displays in the browser tab.
- The guide will be more usable if the reader sees two tabs titled
- "Using Hooks" and "API Usage" instead of "Usage" and "Usage".
- - *In page content:* Insert one heading 1 at the top of each page. In the
- rest of the page, use headings of level 2 and greater.
-- Navigation structure
- - Each page (except "Home") should be contained within one and only one
- folder. The folder serves as a "part" and the page serves as a "chapter"
- which is in keeping with the structure common to most text books and
- manuals. Do not make deeper levels of page hierarchy.
-
-
[Markdown]: markdownrules.md
--
GitLab