1562 Style Guide 1b55350f

Documentation style guide

I. Core principles

1. Clarity: Write for easy understanding. Prioritize clear, direct, and simple language.
2. Consistency: Use consistent terminology, formatting, and style throughout the documentation.
3. Accuracy: Ensure all information is technically correct and up-to-date.
4. Accessibility: Design documentation to be usable by everyone. Focus on semantic structure, clear link text, and image alternatives.
5. Global audience: Write in standard US English. Avoid slang, idioms, and cultural references.
6. Prescriptive: Guide the reader by recommending specific actions and paths, especially for complex tasks.

II. Voice and tone

• Professional yet friendly: Maintain a helpful, knowledgeable, and conversational tone without being frivolous.
• Direct: Get straight to the point. Keep paragraphs short and focused.
• Second person: Address the reader as "you."
• Present tense: Use the present tense to describe functionality (e.g., "The API returns a JSON object.").
• Avoid: Jargon, slang, marketing hype, and overly casual language.

III. Language and grammar

• Active voice: Prefer active voice over passive voice.
  • Example: "The system sends a notification." (Not: "A notification is sent by the system.")
• Contractions: Use common contractions (e.g., "don't," "it's") to maintain a natural tone.
• Simple vocabulary: Use common words. Define technical terms when necessary.
• Conciseness: Keep sentences short and focused, but don't omit helpful information.
• "Please": Avoid using the word "please."

IV. Procedures and steps

• Start each step with an imperative verb (e.g., "Connect to the database").
• Number steps sequentially.
• Introduce lists of steps with a complete sentence.
• Put conditions before instructions, not after.
• Provide clear context for where the action takes place (e.g., "In the administration console...").
• Indicate optional steps clearly (e.g., "Optional: ...").

V. Formatting and punctuation

• Text wrap: Wrap all text at 80 characters, with exceptions for long links or tables.
• Headings, titles, and bold text: Use sentence case. Structure headings hierarchically.
• Lists: Use numbered lists for sequential steps and bulleted lists for all other lists. Keep list items parallel in structure.
• Serial comma: Use the serial comma (e.g., "one, two, and three").
• Punctuation: Use standard American punctuation. Place periods inside quotation marks.
• Dates: Use unambiguous date formatting (e.g., "January 22, 2026").

VI. UI, code, and links

• UI elements: Put UI elements in bold. Focus on the task when discussing interaction.
• Code: Use code font for filenames, code snippets, commands, and API elements. Use code blocks for multi-line samples.
• Links: Use descriptive link text that indicates what the link leads to. Avoid "click here."

VII. Word choice and terminology

• Consistent naming: Use product and feature names consistently.
• Specific verbs: Use precise verbs.
• Avoid:
  • Latin abbreviations (e.g., use "for example" instead of "e.g.").
  • Placeholder names like "foo" and "bar" in examples; use meaningful names instead.
  • Anthropomorphism (e.g., "The server thinks...").
  • "Should": Be clear about requirements ("must") vs. recommendations ("we recommend").

VIII. Files and media

• Filenames: Use lowercase letters, separate words with hyphens (-), and use standard ASCII characters.
• Images: Provide descriptive alt text for all images. Provide high-resolution or vector images when practical.

IX. Accessibility quick check

• Provide descriptive alt text for images.
• Ensure link text makes sense out of context.
• Use semantic HTML elements correctly (headings, lists, tables).