Writing style guide

Standards for production-ready end-user docs.

Voice

  • Use clear, direct language.
  • Prefer “click/select/open” over ambiguous verbs.
  • Match the product’s UI labels exactly.

Structure

  • Start with Purpose and Who this is for.
  • Use numbered steps for procedures.
  • Include Expected result and Troubleshooting on every task page.

Screenshots and videos

  • Videos are optional; use them for complex flows.
  • If a video exists, include it near the top using:
    • <YoutubeEmbed videoId=\"...\" title=\"...\" />
  • Add screenshots later where they remove ambiguity (recommended for production readiness).

Terms

  • Define jargon once in /docs/reference/glossary.
  • Use the same term everywhere (no synonyms for key concepts).