Highlights

AI-generated Key Takeaways

• This style guide outlines important standards for tone, content, language, grammar, formatting, punctuation, organization, and image use in documentation.

• Key recommendations include using conversational language, writing for accessibility and a global audience, employing active voice and second person, and following specific formatting rules for lists, code, and UI elements.

• For clarity, the guide promotes descriptive link text, unambiguous date formats, the use of alt text for images, and the preference for high-resolution images whenever possible.

• This guide aims to ensure consistent, clear, and user-friendly documentation.

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.

Images

• Provide alt text.
• Provide high-resolution or vector images when practical.