Documentation Style Guide

This guide is the distilled, project-specific subset of the rules that matter here. For general English, grammar, and voice questions, defer to the Microsoft Style Guide, then Google’s developer documentation style guide. Do not duplicate their guidance in these pages.

Structure: Diátaxis

Every page belongs to exactly one of four modes:

Mode

Reader asks

Example

Tutorial

"Can you teach me to…?"

tutorial/getting-started.adoc

How-to

"How do I…?"

how-to/write-traceable-items.adoc

Reference

"What does X do?"

reference/cli.adoc

Explanation

"Why does it work that way?"

explanation/architecture.adoc

Rules:

  • One page = one mode. Never mix a how-to step with reference listing or explanation in the same page.

  • Tutorial pages do not link out to Reference or Explanation. They are a guided path.

  • How-to, Reference, and Explanation pages cross-reference each other freely.

  • The Self-Traceability section is not user-facing documentation. It is the extension applied to its own development artifacts.

AsciiDoc mechanics

  • One sentence per line. See the AsciiDoc recommended practices. This keeps diffs line-level and review easier.

  • Use [source,<lang>] blocks for code, commands, and file contents.

  • Use tables for option and reference listings.

  • Use xref: for links between pages and link: for external URLs.

  • Wrap identifiers, commands, options, file paths, and attribute names in backticks.

Titles and headings

  • How-to pages use the How to <verb> <object> format, such as How to Write Traceable Items.

  • Reference pages use a noun phrase, such as Item Macro.

  • Explanation pages name the concept, such as The Traceability Model.

  • Use sentence case for headings.

Scannable content

Readers and AI agents skim, they do not read linearly. Make every page scannable:

  • Write headings that carry meaning on their own. A reader who reads only the headings should still understand the page.

  • Lead with the point. Put the conclusion or the command in the first sentence of each section and paragraph.

  • Prefer lists and tables over prose walls. When a sentence lists three or more parallel items, turn it into a list.

  • Keep paragraphs short: one idea per paragraph.

  • Prefer a concrete example over a description. Show the [item] block or the command, do not only describe it.

  • Make each section self-contained. Do not rely on "as mentioned above"; a section must survive being read or retrieved alone.

  • Keep subjects explicit. Prefer "The build fails on duplicate IDs" over "It fails", so a search or an AI can match the sentence out of context.

These rules help AI agents retrieve and reason about the documentation as much as they help humans skim it.

Search and discoverability

  • Use the reader’s search terms, not internal jargon. Write "duplicate item IDs", not "node collision".

  • Write short, descriptive link text that names the target. Prefer "see the validate command" over "see here".

  • Give every page a meaningful :description: attribute. It becomes the HTML meta description for SEO and social previews.

  • Give every page a meaningful :keywords: attribute. The site’s lunr search index indexes and boosts these terms.

Voice and tone

  • Use second person and imperative for tasks: "Run `validate`", not "The user should run `validate`".

  • Prefer active voice and present tense.

  • Prefer short sentences and plain words.

  • Avoid "please", "just", "simply", "obviously", and "easily".

  • Write behavior in the present tense: "The build fails", not "The build will fail".

Tone.

  • Write conversationally, like you would speak to a colleague. Use contractions: "don’t", "you’ll".

  • Be friendly and approachable, but never at the cost of precision.

  • Be respectful. Assume the reader is competent; do not condescend.

  • Prefer natural over formal. Prefer "you" over "the user" and "get" over "obtain" when it reads better.

  • Casual is fine as long as the instruction stays unambiguous and professional.

Inclusive language

Write for every reader. Two rules cover most cases:

Bias-free communication. Do not assume or stereotype the reader:

  • Use "they" as the singular pronoun, and prefer "staffed", "chairperson", and "humankind" over gendered terms.

  • Avoid ableist terms. Prefer "surprising" over "crazy", "broken" over "lame", "unaware of" over "blind to", and "ignored" over "fell on deaf ears".

  • Refer to people by role, not by background, age, or ability.

Non-militaristic language. Avoid war and violence metaphors. Name the action instead:

Instead of

Use

war room

incident room

kill switch

emergency stop

battle-tested

well-tested

attack the problem

solve the problem

blitz through

complete quickly

Keep established technical terms as-is when they are the standard name of a concept, but do not coin new militaristic terms. In new text, prefer inclusive alternatives such as "allowlist/denylist" and "primary/replica".

For the full treatment, see the Microsoft bias-free communication guidance and Google’s inclusive documentation guidance.

Requirements style

Requirements written as [item] blocks follow the EARS patterns:

Pattern

Shape

Ubiquitous

The system SHALL <verb> <object>.

Event-driven

WHEN <trigger>, the system SHALL <verb> <object>.

State-driven

WHILE <state>, the system SHALL <verb> <object>.

Unwanted behaviour

IF <condition>, THEN the system SHALL <verb> <object>.

Optional

WHERE <feature>, the system SHALL <verb> <object>.

A requirement states what the system must do, never how:

[#REQ-001, item, role=requirement, title="REQ-001 — Fail on duplicate IDs"]
--
The build SHALL fail when two items define the same ID.
--

Each requirement must be testable, atomic, and unambiguous. See the requirements-writing skill for a full checklist.

Commit messages

Commits follow Conventional Commits:

<type>(<scope>): <description>

Types: feat, fix, docs, style, refactor, test, chore, ci, perf.

Further reading