docs-style

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?

The reader's stance	Type
"I'm learning — guide my hands"	Tutorial
"I have a goal — help me reach it"	How-To
"I'm working — let me look something up"	Reference
"I'm reflecting — help me understand why"	Explanation

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.

Voice and Tone

Use Second Person

Address the reader directly as "you" rather than "the user" or "developers."

<!-- Good -->
You can configure the API by setting environment variables.

<!-- Avoid -->
The user can configure the API by setting environment variables.
Developers should configure the API by setting environment variables.

Prefer Active Voice

Write sentences where the subject performs the action. Active voice is clearer and more direct.

<!-- Good -->
Create a configuration file in the root directory.
The function returns an array of user objects.

<!-- Avoid -->
A configuration file should be created in the root directory.
An array of user objects is returned by the function.