Chapter 16 — Technical documentation and safety
Lesson map
Lesson 16 published. Map, example, EX061.
flowchart TD
N0["Learning outcomes"]
N1["16.1 Runbooks"]
N2["16.2 Safety warnings"]
N3["16.3 Versioning"]
N4["16.4 Retirement"]
N5["16.5 Audience"]
N6["16.6 Review cadence"]
N7["16.7 Screenshots in runbooks"]
N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> N6 --> N7
N7 --> EX["Worked example"]
EX --> Q["Exercise EX061"]
Logical drawing
flowchart LR
N0["Learning outcomes"]
N1["16.1 Runbooks"]
N2["16.2 Safety warnings"]
N3["16.3 Versioning"]
N4["16.4 Retirement"]
N5["16.5 Audience"]
N6["16.6 Review cadence"]
N7["16.7 Screenshots in runbooks"]
N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> N6 --> N7 --> Q["EX061"]
[Learning outcomes]
|
v
[16.1 Runbooks]
|
v
[16.2 Safety warnings]
|
v
[16.3 Versioning]
|
v
[16.4 Retirement]
|
v
[16.5 Audience]
|
v
[16.6 Review cadence]
|
v
[16.7 Screenshots in runbooks]
|
v
[Worked example] --> [Exercise EX061]
Learning outcomes
You will (1) write runbooks for authorized checks; (2) keep safety warnings visible; (3) version documents; (4) retire obsolete methods.
16.1 Runbooks
Step-by-step for each recurring check, with ROE references and stop conditions at the top in bold.
The ENG-512 runbook covers kickoff, method cards, stop messages and cleanup. Each ticket cites the runbook git hash, and every peer pastes the same hash into their notebook at kickoff as a receipt. That way everyone works from one version of the kickoff and stop chapters, and a later edit to the runbook cannot leave two technicians following different stop rules during the same Saturday window.
16.2 Safety warnings
Do not run against production is the first line of the staging port-diff runbook.
Page one of every runbook states the safety warnings: the fare network is black and freestyle scanning is forbidden. Audit samples always open page one first, and a runbook whose fare warning appears only on a late page fails the sample and has its ticket reopened. Warnings buried on page nine do not protect anyone, because a technician working under time pressure reads the opening steps and rarely the appendix.
16.3 Versioning
Documents show version, date and owner; old versions archived.
Runbook versions are tracked with git tags, and Sam will not follow a printed copy older than the tag named in the ROE. The kickoff checklist includes a git describe against that tag; if the output does not match, kickoff is cancelled until the copy is aligned. A printed page can be convenient at the desk, but only the tagged version is authoritative when a stop rule or contact has changed.
16.4 Retirement
Methods that used retired tools are marked obsolete so newcomers do not follow them.
Retirement also removes cards that mention decommissioned hosts. Those cards move to the archive in the same week that the host is decommissioned, so a stale check cannot return to the stack on the next Saturday. Leaving retired pages in the active library would confuse the next window, because a newcomer could follow a method aimed at a host that no longer exists or now belongs to someone else.
16.5 Audience
Write for a technician who was out sick during the last engagement.
The readers are technicians and the SOC, not marketing, so each step is written so that a technician who missed ENG-512 can follow it at night without calling Sam. Stop conditions appear in plain words, with an example of the halt message to post. Slogans and praise for tools are edited out before the technician edition is published, because they add length without helping anyone decide what to do.
16.6 Review cadence
Runbooks reviewed every six months or after any stop incident.
An architecture change also triggers a review, even when the six-month date is still some way off. A missed review opens a programme debt ticket that carries an owner and a due date like any finding, and the CISO pack lists open documentation debt beside the technical findings. Making the debt visible keeps outdated runbooks from drifting quietly until the next stop incident exposes them. Each review is logged with the runbook tag it produced, so readers can see when a page was last confirmed.
16.7 Screenshots in runbooks
Runbooks prefer text steps over screenshots that rot when the UI changes. Where screenshots help, they are dated.
All screenshots in runbooks are synthetic and redacted; real rider screens never illustrate a procedure. The same CI that builds the course materials rejects pull requests that add non-synthetic rider screenshots, so the policy does not depend on reviewers noticing. Synthetic figures still show the steps clearly, and they remove the risk that a training document becomes an accidental store of rider personal data.
16.8 Translation
If a contractor shift speaks another language, critical stop warnings appear in both languages used on site.
The wording of stop phrases is agreed once with the SOC and then reused, rather than improvised during an incident. Freelanced empathy or softened wording in a stop message is not a control. The agreed halt phrases are versioned beside the ethics charter excerpt, so any edit to them needs the same owners as an edit to the ethics text and cannot slip in unnoticed between windows.
16.9 Field discipline
When a stop incident happens, Sam updates the runbook the same week or files a ticket why not. Documentation delayed until "after the busy period" is documentation that never happens. His managers accept shorter runbooks that are current over long ones that describe retired tools.
Field discipline for documentation is versioned, warned, retired cleanly, synthetic screenshots. Sam's ENG-512 depends on the tagged runbook, not memory. A runbook that cannot be followed without asking Sam is treated as unfinished, whatever its length or polish.
16.10 Closing note
Obsolete runbooks are moved to an /archive folder that CI checks no active link points to. Broken links to retired methods fail the documentation build.
Documentation is how NMT survives Sam's holiday. A deputy must be able to find the stop phrases and the fare exclusion in the runbook without asking Sam, so a missing stop phrase is treated as a defect rather than a style choice. When the documents are complete and current, the programme can keep testing safely while the usual lead is on leave.
16.11 Extra
Sam prints the stop-conditions page of the active runbook and keeps it on the desk during windows — screens lock, paper still readable when seconds matter.
As an extra, Sam keeps a one-page ENG-512 cheat sheet taped beside the jump host. It carries the ROE date, the emergency contacts and the fare exclusion, and it is replaced whenever the ROE date rolls forward. A sheet that matches the current ROE gives the technician the essential limits at a glance, without opening a document while a stop is in progress.
Worked example (synthetic NMT)
Sam's runbook v1.3 opens with STOP CONDITIONS and OUT OF SCOPE: fare network, then the port-diff steps.
Synthetic case — Northline Municipal Transit (NMT). The transit agency, Sam Park and all figures are invented for teaching.
Errors and limits
Live transit systems and fare equipment are never tested without a separate, specialised authorization. This book uses synthetic data only and grants no authority to test real systems.
Exercises
- EX061 — Top of runbook. What two blocks sit at the top? Rubric: 3 = stop conditions and ROE/out-of-scope; 2 = one; 1 = history; 0 = none.
- EX062 — First line. What is the first line of the staging port-diff runbook? Rubric: 3 = do not run against production; 2 = partial; 1 = install tool; 0 = none.
- EX063 — Obsolete. What should happen to a runbook for a retired tool? Rubric: 3 = mark obsolete/archive; 2 = partial; 1 = leave as-is; 0 = none.
- EX064 — Review trigger. When must runbooks be reviewed outside the six-month cadence? Rubric: 3 = after a stop incident (or major change); 2 = partial; 1 = never; 0 = none.
Synthesis
Documentation puts safety first, stays versioned and retires with its tools.
Continue studying — chapter 16 of 18
← Chapter 15 (draft) · Course chapter index · Chapter 17 (draft) →