The style guide covers a lot of material, so the following page provides an overview of its most important points. For more information about topics on the page, follow the links.
Tone and content
- Be conversational and friendly without being frivolous.
- Don't pre-announce anything in documentation.
- Use descriptive link text.
- Write accessibly.
- Write for a global audience.
Language and grammar
- Use second person: "you" rather than "we."
- Use active voice: make clear who's performing the action.
- Use standard American spelling and punctuation.
- Put conditions before instructions, not after.
- For usage and spelling of specific words, see the word list.
Formatting, punctuation, and organization
- Use sentence case for document titles and section headings.
- Use numbered lists for sequences.
- Use bulleted lists for most other lists.
- Use description lists for pairs of related pieces of data.
- Use serial commas.
- Put code-related text in code font.
- Put UI elements in bold.
- Use unambiguous date formatting.
- Use SVG files or crushed PNG images.
- Provide alt text.
- Provide high-resolution images when practical.