Skip to content

Documentation rules

This page states how documentation is written and what a documentation change MUST satisfy. These rules bind every wiki page, every README.md and every code comment.

Writing

DOC-1: Use simple sentence forms

Write in these shapes:

  • If <this>, then <that>.
  • <this> is good. <that> is bad.
  • <this> is <adjective> because <that>.
  • <this> MUST <do that>.
  • <this> MUST NOT <do that>.
  • <this> SHOULD <do that>.
  • <this> SHOULD NOT <do that>.
  • <this> MAY <do that>.
  • DO <this>.
  • DO NOT <this>.
  • These are the following: a, b, c.
  • These are <adjective>.

A label line such as Enforcement: *Review only.* is also allowed.

Enforcement: Review only.

DOC-2: One sentence, one idea

  • A sentence MUST NOT exceed 25 words.
  • DO NOT join clauses with an em-dash, a semicolon or a colon. Split the sentence instead.
  • A colon before an enumeration is allowed.

Enforcement: Review only.

DOC-3: Prefer a list over a table and long paragraphs

  • If the content is a set of items, then write a list.
  • If the items happen in a fixed order, then number them. Otherwise do not.
  • If every item has the same attributes and the reader compares them, then write a table.
  • DO NOT write a set of items as a paragraph.

Enforcement: Review only.

DOC-4: Headings MUST be sentence case

  • You MUST capitalise the first word and any proper noun. Nothing else.
  • This binds every heading, page title, nav label and link text.
  • An RFC 2119 keyword stays uppercase. These are the following: MUST, MUST NOT, SHOULD, SHOULD NOT, MAY.
  • An identifier keeps the casing it has in the code. Examples: X-Async, cuDNN, torch.utils.bottleneck.

Changing casing:

  • Changing capitalisation is safe. MkDocs lowercases when it generates the anchor.
  • Changing the words breaks every link to that heading. Fix them in the same change (DOC-6).
  • DO give a heading an explicit { #stable-id }. It survives rewording.

Enforcement: Review only.

DOC-5: Write for an expert reader

DO assume that the reader knows the domain, the technology, the codebase and the use case, and shares the goals.

  • DO NOT define a term the team uses daily.
  • DO NOT restate or explain what the code or the surrounding page already says.
  • DO NOT sell a decision.
  • DO NOT write about history, or how we got here.
  • DO NOT write any extra information that is not needed.

Enforcement: Review only.

Changing documentation

DOC-6: Documentation MUST be changed in the same commit and PR

You MUST update the documentation in the same commit and the same pull request.

This binds a change to any of the following: code, a build task, a workflow, a deploy path, a service contract, tool usage.

DO NOT defer it to a follow-up or a ticket.

See principle 9.

Enforcement: Review only.

DOC-7: You MUST NOT write prose in the repository

A README.md MUST only say what a directory is. It MUST link to the page explaining it.

DO NOT write longer prose in a Markdown file outside docs/wiki/docs/.

Enforcement: Review only.

DOC-8: All documentation pages MUST have a nav entry

A new page MUST have the Markdown file and an entry in mkdocs.yml.

Enforcement: none.

Rule pages

DOC-9: A rule MUST state the requirement, not narrate the failure

  • Use MUST, MUST NOT, DO and DO NOT.
  • DO phrase the requirement so the reason is implicit.
  • You MAY add one short sentence of reason where the requirement cannot carry it.
  • DO NOT narrate the failure the rule prevents.
  • If the reasoning needs more than one sentence, then put it in an explanation page and link to it.

Enforcement: Review only.

DOC-10: A rule MUST name what enforces it

Every rule MUST end with an Enforcement: line. DO name a check, or say Review only, or say none.

Enforcement: Review only.