Documentation Style Guide

Apply these principles when writing or reviewing documentation to ensure clarity, consistency, and accessibility for both human readers and LLMs.

Choose the Right Documentation Type First

Style serves a purpose, and the purpose depends on which of the four Diataxis types you are writing. Before applying the conventions below, decide whether the document is a Tutorial (learning), How-To guide (a task), Reference (looking up), or Explanation (understanding) — these are not interchangeable, and mixing them in one document weakens all of them.

To choose, ask the two compass questions: action or cognition? acquisition or application?

For the full decision procedure, the 2×2 map, the two distinctions that resolve most ambiguity (Tutorial vs. How-To, Reference vs. Explanation), and the quality model, see references/diataxis-compass.md. The type-specific skills (tutorial-docs, howto-docs, reference-docs, explanation-docs) build on the principles in this guide once the type is chosen.