Chapter 16 — Technical documentation and safety
Lesson map
Lesson 16 published. Map, example, EX061.
flowchart TD
N0["Learning outcomes"]
N1["16.1 Runbooks that work"]
N2["16.2 Documenting without secrets"]
N3["16.3 Production safety"]
N4["Synthesis"]
N0 --> N1 --> N2 --> N3 --> N4
N4 --> EX["Worked example"]
EX --> Q["Exercise EX061"]
Logical drawing
flowchart LR
N0["Learning outcomes"]
N1["16.1 Runbooks that work"]
N2["16.2 Documenting without secrets"]
N3["16.3 Production safety"]
N4["Synthesis"]
N0 --> N1 --> N2 --> N3 --> N4 --> Q["EX061"]
[Learning outcomes]
|
v
[16.1 Runbooks that work]
|
v
[16.2 Documenting without secrets]
|
v
[16.3 Production safety]
|
v
[Synthesis]
|
v
[Worked example] --> [Exercise EX061]
Learning outcomes
You will (1) write runbooks that another technician can follow; (2) document cryptographic settings without exposing secrets; (3) apply safety rules to production work.
16.1 Runbooks that work
Tomás's first runbook, for renewing the file-transfer host certificate, assumed knowledge only he had. Priya asks a colleague to follow it, and the colleague stops at step three. Tomás rewrites it with prerequisites, exact commands, expected outputs, a check after each step and a rollback section. He adds who to call if a step fails. A runbook is tested by someone else using it, not by its author reading it again. Good runbooks turn one person's expertise into a team capability and shorten outages at three in the morning.
16.2 Documenting without secrets
Documentation must describe where secrets live without containing them. Tomás writes that the payment callback secret is stored in the vault under a named path, accessible to svc-portal, rotated every 180 days, rather than writing the secret. He documents TLS settings, certificate profiles and key sizes openly, because these are not secret, and Kerckhoffs's principle says a system should remain secure even when its design is public. He reviews every document with a search for patterns that look like keys or passwords before publishing it to the team wiki.
16.3 Production safety
Priya's safety rules for production cryptographic work are short: have an approved change, a tested rollback and a second person available; never disable verification to restore service; never move private keys by email, chat or removable media; and stop and escalate if anything unexpected appears. Tomás adds his own rule: announce work in the operations channel before starting and when finished. These rules exist because cryptographic mistakes can lock out every user at once, and a calm, checked process prevents a small error from becoming a company-wide outage.
Worked example
Tomás rewrites the renewal runbook after a colleague's test, documents the callback secret by vault path only and lists the production safety rules at the top.
Synthetic case. Runbook steps and vault paths are synthetic.
Errors and limits
Runbooks age as systems change; review them after each use. Secret scanners miss unusual formats.
Exercises
- EX061 — Runbook test. How is a runbook properly tested? Rubric: 3 = someone other than the author follows it and reports gaps;; 2 = colleague follows;; 1 = author rereads;; 0 = none.
- EX062 — Kerckhoffs. Why can TLS settings and key sizes be documented openly? Rubric: 3 = security should rest on keys, not secrecy of design (Kerckhoffs);; 2 = names principle;; 1 = settings secret;; 0 = none.
- EX063 — Secret entry. How should the runbook refer to the callback secret? Rubric: 3 = by vault path, accessing account and rotation period, never the value;; 2 = path;; 1 = includes value;; 0 = none.
- EX064 — Never restore by. Name one shortcut the safety rules forbid when restoring service. Rubric: 3 = disabling verification, or moving keys by email or chat;; 2 = one shortcut;; 1 = vague;; 0 = none.
Synthesis
Documentation makes cryptographic operations repeatable and safe when it is tested by others and describes secrets without revealing them.
Continue studying — chapter 16 of 18
← Chapter 15 (draft) · Course chapter index · Chapter 17 (draft) →