Chapter 16 — Technical documentation and safety
Lesson map
Lesson 16 published. Map, example, EX061.
flowchart TD
N0["Learning outcomes"]
N1["16.1 Writing for the reader"]
N2["16.2 Safety and privacy cautions"]
N3["16.3 Keeping documents current"]
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 Writing for the reader"]
N2["16.2 Safety and privacy cautions"]
N3["16.3 Keeping documents current"]
N4["Synthesis"]
N0 --> N1 --> N2 --> N3 --> N4 --> Q["EX061"]
[Learning outcomes]
|
v
[16.1 Writing for the reader]
|
v
[16.2 Safety and privacy cautions]
|
v
[16.3 Keeping documents current]
|
v
[Synthesis]
|
v
[Worked example] --> [Exercise EX061]
Learning outcomes
You will (1) write clear technical documentation; (2) include safety and privacy cautions; (3) keep documents current.
16.1 Writing for the reader
Nadia rewrites Linden's scattered notes into a short documentation set: a network diagram per practice, the firewall rule list with purposes, device baselines, response cards and runbooks for routine tasks. She writes for the person who will use each document under pressure, often a practice manager during an outage. Each document starts with its purpose and who should use it, uses numbered steps and avoids jargon. Daniel reminds her that documentation is judged by whether someone else can follow it correctly without help.
16.2 Safety and privacy cautions
Some tasks carry risks to patients or data. Restarting the imaging server during clinic hours could interrupt an X-ray in progress, so the runbook says to check with surgeries first. Exporting logs for an investigation could expose patient names, so the runbook says to store exports only in the restricted log folder. Nadia places cautions directly before the step they apply to, not in a separate section, because people under pressure skip general warnings but notice ones placed where they act.
16.3 Keeping documents current
Documents age fast. Nadia adds a version, date and owner to each and links updates to the change procedure: any change to a network, rule or device must update the matching document before the change is closed. Grace schedules a quarterly check where one practice manager follows a runbook and reports problems. The first check finds a screenshot from an older router interface. Treating documents as part of the system, not as an afterthought, keeps them useful when they are needed most.
Worked example
Nadia writes reader-focused documents with in-step safety and privacy cautions and links updates to change control and quarterly checks.
Synthetic case. Documents and checks are synthetic.
Errors and limits
Documents drift when changes skip the procedure. Too many cautions dilute attention.
Exercises
- EX061 — Test of documentation. How is documentation judged? Rubric: 3 = whether someone else can follow it correctly without help;; 2 = usability;; 1 = length;; 0 = none.
- EX062 — Imaging restart caution. What caution applies to restarting the imaging server? Rubric: 3 = check with surgeries first to avoid interrupting an X-ray;; 2 = check surgeries;; 1 = vague;; 0 = none.
- EX063 — Placing cautions. Where should cautions be placed? Rubric: 3 = directly before the step they apply to;; 2 = in-step;; 1 = appendix;; 0 = none.
- EX064 — Quarterly check finding. What did the first quarterly check find? Rubric: 3 = an outdated router screenshot;; 2 = screenshot;; 1 = vague;; 0 = none.
Synthesis
Good technical documentation is written for its user, places cautions where they act and stays current through change control.
Continue studying — chapter 16 of 18
← Chapter 15 (draft) · Course chapter index · Chapter 17 (draft) →