Documentation style guide#

Every documentation page follows the rules on this page. Reviewers cite this guide during pull request review.

Language and tone#

The documentation is written in English. The voice is third person present tense. Avoid marketing tone, exclamation marks, and the words obviously, simply, just.

Punctuation#

Prose uses periods, commas, and question marks only.

Forbidden in running prose.

; : outside of a list lead in (such as See also:) Em dash — En dash –

Allowed everywhere.

These characters belong in code, paths, RST role syntax, headings, frontmatter, and inside list items that name two parallel items.

ASCII art and pipes#

ASCII art is forbidden in running prose. Tables use .. list-table:: or .. csv-table::. The | character appears only in code blocks and in RST substitutions.

Diagrams#

Every diagram is a .. mermaid:: block inside the page. External Excalidraw, PlantUML, and SVG sources are not used.

Sentences#

One sentence per line (semantic newlines). Each statement is a complete sentence. No fragments.

Paragraphs#

Two to five sentences per paragraph. When the scope changes, introduce a new heading rather than a sixth sentence.

Headings#

RST underlines use =, -, ~, ^. One H1 per file. Sentence case for every heading. Capitalize the first word, proper nouns (Django, Python, Sphinx, Vite), and acronyms (URL, DI, CSRF). Code identifiers in headings keep their exact spelling. A heading never ends with punctuation.

Code blocks#

Use .. code-block:: <language> with an explicit language. Add a :caption: that names the file. DJX and Django templates use jinja as the language for syntax highlighting.

Example.

notes/pages/template.djx#
<h1>{{ title }}</h1>
Forbidden inside code blocks meant to be runnable.

... ellipses. Shell prompts ($, >>>) except in transcript blocks.

Cross references#

Use :doc: for whole page links. Use :ref: for anchors. Every topic page declares an anchor at the top in the form .. _topics-<area>:.

Admonitions#

Do not use .. versionadded:: or .. versionchanged:: in user-facing documentation. Release history belongs in the release notes of each pull request, not in the manual. This matches the version policy in Writing documentation.

Allowed types.

  • .. note:: for nonessential context.

  • .. warning:: for foot guns.

  • .. seealso:: for sibling links.

Each admonition holds one paragraph.

Inline code#

Double back ticks for code, paths, configuration keys, and signal names.

Lists#

Each list item is a complete sentence ending in a period. Items in one list share grammar (all noun phrases, all verb phrases, all complete sentences).

Page templates#

Read Writing documentation for the section specific templates. Templates apply consistently inside each section.

Pull request checklist#

A documentation pull request lands when.

  • make docs is green.

  • uv run doc8 docs/content is green.

  • Every new section follows its template.

  • Every page under content/internals/ includes a .. mermaid:: diagram.

  • Cross references resolve.

  • Runnable excerpts follow the Notes tutorial paths or name another reference project.

  • Blurbs for examples/ stay aligned with examples/README.md.

Repository Markdown#

README.md and CONTRIBUTING.md follow a relaxed subset of these rules. Em dashes are allowed inside list items and table cells as separators between a term and its description. Running prose paragraphs avoid em dashes and semicolons, the same as RST prose. Semicolons do not join independent clauses in any context. Each independent clause begins a new sentence.

See also#

See also

Writing documentation for the broader workflow. Contributor notes for code conventions.