Writing
Style Guide
Guidelines for documentation including grammar, voice and tone, formatting, word use, and more.
A consistent style, voice, and tone is important to make documentation easy to read and feel cohesive. Projects documented on this website will rely on several external resources to ensure that documentation is written well.
Primary Style Guide
Projects should follow Google’s Developer Documentation Style Guide unless there is a strong reason to diverge from the advice given there.
Additional information
There are a few additional guidelines specific to this website that should be kept in mind.
Comprehensive documentation
Don’t omit information from project documentation because it may be risky or only address rare cases. Users experiencing the types of problems that this kind of documentation will help with are precisely the people who need that documentation. Users should be fully informed by fully-detailed caveats and warnings.
Word choice
The Google style guide includes many specific guidelines for words to use or not use in various contexts. There are a few additional cases for this documentation website:
- section
- A section refers to the groups of content within a project.
- site
- Don’t use. Instead, use website (or facility if speaking about a physical location)
- page
- Refers to a specific piece of documentation within a section.
- project
- A project refers to the top-level section of this documentation website (you are currently reading the Meta project).
Projects may additionally document preferred usage and style for terms related to that project. Those terms (if present) should be documented on a supplemental style guide page within the project documentation.
External resources
- Google offers a free technical writing course
- Apple’s Style Guide is worth reading. Google’s style guide was chosen because it was more comprehensive than Apple’s guide.