22 KiB
styleguide Markdown style guide
Much of what makes Markdown refreshing is the ability to write plain text and get great formatted output as a result. To keep the slate clean for the next author, your Markdown should be simple and consistent with the whole corpus wherever possible.
We seek to balance three goals:
Source text is readable and portable. The Markdown corpus is maintainable over time and across teams. The syntax is simple and easy to remember.
Contents:
Minimum viable documentation Better is better than best Capitalization Document layout Table of contents Character line limit Trailing whitespace Headings ATX-style headings Use unique, complete names for headings Add spacing to headings Use a single H1 heading Capitalization of titles and headers Lists Use lazy numbering for long lists Nested list spacing Code Inline Use code span for escaping Codeblocks Declare the language Escape newlines Use fenced code blocks instead of indented code blocks Nest codeblocks within lists Links Use explicit paths for links within Markdown Avoid relative paths unless within the same directory Use informative Markdown link titles Reference links Use reference links for long links Use reference links to reduce duplication Define reference links after their first use Images Tables Strongly prefer Markdown to HTML Minimum viable documentation
A small set of fresh and accurate docs is better than a sprawling, loose assembly of “documentation” in various states of disrepair.
The Markdown way encourages engineers to take ownership of their docs and keep them up to date with the same zeal we keep our tests in good order. Strive for this.
Identify what you really need: release docs, API docs, testing guidelines. Delete cruft frequently and in small batches. Better is better than best
The standards for an internal documentation review are different from the standards for code reviews. Reviewers should ask for improvements, but in general, the author should always be able to invoke the “Better/Best Rule.”
Fast iteration is your friend. To get long-term improvement, authors must stay productive when making short-term improvements. Set lower standards for each CL, so that more such CLs can happen.
As a reviewer of a documentation CL:
When reasonable, LGTM immediately and trust that comments will be fixed appropriately. Prefer to suggest an alternative rather than leaving a vague comment. For substantial changes, start your own follow-up CL instead. Especially try to avoid comments of the form “You should also…”. On rare occasions, hold up submission if the CL actually makes the docs worse. It’s okay to ask the author to revert.
As an author:
Avoid wasting cycles with trivial argument. Capitulate early and move on. Cite the Better/Best Rule as often as needed. Capitalization
Use the original names of products, tools and binaries, preserving the capitalization. E.g.:
Markdown style guide
Markdown is a dead-simple platform for internal engineering documentation.
and not
markdown bad style guide example
markdown is a dead-simple platform for internal engineering documentation.
Document layout
In general, documents benefit from some variation of the following layout:
Document Title
Short introduction.
[TOC]
Topic
Content.