Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Style Guide

This document describes the style guide used for technical writing in the Arminius project.

Tone and Style

Language

  • Write all documentation in English.
  • Use simple, clear language.
  • Replace idioms with plain phrasing.
  • Keep humour and cultural references light and easy to ignore.
  • Prioritise clarity over elegance.
  • Use short, direct sentences.
  • Spell and format consistently—use British English spelling (“colour”, “authorise”, “behaviour”).

Voice and Tense

  • Use active voice: “The API returns an error” instead of “An error is returned.”
  • Use present tense: describe the system’s current state, not what it “will” or “should” do.

Precision and Brevity

  • Include only what the reader needs to complete a task or understand a concept.
  • Be specific: “The process runs every 10 minutes” instead of “The process runs regularly.”
  • Avoid filler phrases like “It should be noted that…” or “Basically…”.

Consistency and Neutrality

  • Use consistent terminology across all documents. If a term exists in the glossary, use it exactly.
  • Maintain a neutral, professional tone.
  • Avoid first-person pronouns (I, we, ours).
  • Address the reader in the second person (you, your).
  • Use singular they as a gender-neutral pronoun.
  • Use full words instead of abbreviations unless the abbreviation is widely recognised. Spell out abbreviations on their first use in a document.

Structure and Format

General Layout

  • Use mdBook flavoured markdown.
  • Start each document with a one-line summary of its contents. Example: “This document describes the deployment and configuration of the user service.”
  • Keep paragraphs short—3 to 5 sentences each.
  • Use bulleted lists for unordered information and numbered lists for sequential steps.
  • Avoid nesting lists more than one level deep.

Prose Linting

Vale checks the Markdown under docs/ against the Vale and Google style packages. A pre-commit hook and CI both run it.

  • Run vale docs in the devshell to see the same results locally. Editors get them through the vale-ls language server, which the devshell also provides. Leave its configPath unset, or it loses the project styles.
  • Vale flags every word its dictionary lacks. Correct the prose when the word is a genuine misspelling.
  • Add a term Vale should accept to nix/vale/words.txt, or to nix/vale/names.txt when only one capitalisation is correct. Both files describe their own format.

Vale also checks the comments in Rust files, parsed as Markdown like rustdoc does. Rules for Rust are enabled one at a time in the [*.rs] section of nix/vale/vale.ini.

  • Run vale --glob='*.rs' crates in the devshell to check them locally.
  • Put code and identifiers in backticks, and URLs in angle brackets (<https://…>), so Vale skips them.