Skip to content

Technical Writing Guidelines

This guideline helps create clear, complete, and maintainable technical documentation. It applies to README files, ADRs, architecture notes, coding guidelines, feature specifications, runbooks, and similar documents.

Audience and Purpose

  • Define the intended audience before writing.
  • State the purpose of the document clearly: what problem it solves, what decision it supports, or what task it explains.
  • Match the level of detail to the reader's background and the task at hand.
  • Prefer explicit, concrete language over vague abstractions.

Structure and Flow

  • Start with the most important information and then drill down into the details.
  • Order content logically: context, prerequisites, procedure, expected outcome, troubleshooting, and references.
  • Keep sections short and focused; one idea per section.
  • Use headings and bullet points that mirror the reader's questions or tasks.
  • Put prerequisites and assumptions before step-by-step instructions.

Writing Style

  • Prefer short, simple sentences over long, nested ones.
  • Use active voice and direct instructions whenever possible.
  • Prefer concrete nouns and verbs over abstract or ornamental wording.
  • Be precise about requirements, constraints, and outcomes.
  • Avoid unnecessary filler and repetition.
  • Define acronyms and domain-specific terms on first use.

Content Quality

  • Explain concepts and intent, not only implementation details.
  • Document the why as well as the how when the rationale affects the reader's decisions.
  • Include examples, edge cases, and failure modes where they increase clarity.
  • Keep a consistent level of abstraction; avoid mixing high-level explanation with low-level minutiae.
  • Favor wording that survives growth: omit specifics with no lasting meaning (e.g. "each image", not "six images").
  • Update documentation when behavior, interfaces, or workflows change.

Diagrams and Examples

  • Use diagrams when they clarify structure, behavior, state, or flow.
  • Prefer Mermaid.js or PlantUML for Markdown-based documentation when the visual representation adds value.
  • Keep diagrams legible, labeled, and consistent with the surrounding text.
  • Use code examples that are realistic, minimal, and easy to understand.

Review and Maintenance

  • Review documentation for correctness, completeness, and consistency with the actual system.
  • Keep terminology, naming conventions, and references consistent across the repository.
  • Link related documents rather than duplicating content.
  • Treat documentation as a first-class artifact, not as an afterthought.

References

  • The Elements of Style — William Strunk Jr. & E. B. White, 4th ed., 1999
  • Docs Like Code — Anne Gentle, 2017
  • The Chicago Manual of Style — University of Chicago Press, 17th ed., 2017
  • Technical Writing Courses — Google (online, developers.google.com/tech-writing)
  • Write the Docs — community documentation resource (guides, blog, conferences)
  • The Documentation System — Divio (online resource, four-part framework)

Directives

  • Write for a defined audience and purpose; start with the most important information
  • Use short, direct sentences; prefer active voice and concrete wording
  • Structure docs as context → prerequisites → steps → outcome → troubleshooting → references
  • Keep a consistent abstraction level; document intent as well as implementation
  • Favor invariant wording over volatile specifics (counts, exact names) that add maintenance burden without adding meaning
  • Use diagrams (Mermaid/PlantUML) when they clarify structure or flow
  • Keep docs accurate, current, and aligned with the codebase
  • Define acronyms and domain-specific terms on first use
  • Include examples, edge cases, and failure modes where they increase clarity
  • Link related documents rather than duplicating content