How we write documentation¶
NRL-MAN-001 · version 1.0.0 · Public
Our documents are written for the person who has to act on them, often for the first time, sometimes under pressure.
Every procedure has the same parts¶
- Purpose — one sentence: what this does and why.
- Who — the role (Operator or Administrator) and the access it needs.
- When — the trigger or schedule.
- Before you start — prerequisites, time needed, risk, what is affected, backups to take.
- Steps — numbered, one action each, the exact command copy-pasteable. After each step, the expected result; if it can go wrong, what to do if not.
- Verify — how to prove it worked.
- Roll back — how to undo it, or cannot be undone.
- Escalate — who to contact and what to send them.
Rules¶
- Plain verbs: open, type, wait. Never "simply" or "just".
- Every term defined the first time it is used.
- A procedure is tested on a clean system before it is published; until then it carries an UNTESTED banner.
Every document is controlled¶
| Field | Meaning |
|---|---|
| ID | NRL-<TYPE>-<NNN>, for example NRL-RB-004 for a runbook |
| Version | semantic versioning; a new version supersedes, never overwrites |
| Status | draft, in review, approved, published, superseded, retired |
| Classification | Public, Internal, Confidential, Restricted |
| Review | runbooks after every change or yearly; policies yearly |
Only approved documents are published. The full list is in the document register.