Skip to main content

Writing Style

Core principles​

  • Write for the declared audience and expected task.
  • Prefer plain, direct language and short sentences.
  • Use active voice when the actor is known.
  • Address the reader as “you” in procedures.
  • State prerequisites, consequences, and expected results explicitly.
  • Separate verified facts from recommendations, examples, and assumptions.
  • Never infer or invent product behavior to fill a content gap.

Voice and tone​

Use a professional, neutral, and respectful tone. Be precise without sounding legalistic. Avoid marketing language, humor that may not translate, idioms, and unnecessary superlatives.

Terminology​

Use one approved term for each concept. Match names to verified source material and preserve capitalization used by the authoritative source. Define unfamiliar terms on first use and add durable terms to the glossary.

Do not use abbreviations before defining them. Avoid role, feature, or system names that have not been confirmed.

Procedures​

  • Begin each step with an imperative verb.
  • Put one primary action in each numbered step.
  • Identify where the action occurs.
  • Include the expected result when it confirms success.
  • Use notes and warnings only when they materially affect the task.
  • Do not hide required actions inside explanatory paragraphs.

Inclusive language​

Use role-based and gender-neutral language. Avoid assumptions about geography, ability, culture, device, or technical experience. Follow the accessibility standard for content that depends on visual, auditory, or interactive cues.