Chapter 16 — Technical documentation and safety
Lesson map
Lesson 16 published. Map, example, EX061.
flowchart TD
N0["Learning outcomes"]
N1["16.1 The installation procedure"]
N2["16.2 The update procedure"]
N3["16.3 Safety rules"]
N4["16.4 Writing clearly"]
N5["16.5 Keeping current"]
N6["16.6 Where documents live"]
N7["Checking tickets"]
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 The installation procedure"]
N2["16.2 The update procedure"]
N3["16.3 Safety rules"]
N4["16.4 Writing clearly"]
N5["16.5 Keeping current"]
N6["16.6 Where documents live"]
N7["Checking tickets"]
N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> N6 --> N7 --> Q["EX061"]
[Learning outcomes]
|
v
[16.1 The installation procedure]
|
v
[16.2 The update procedure]
|
v
[16.3 Safety rules]
|
v
[16.4 Writing clearly]
|
v
[16.5 Keeping current]
|
v
[16.6 Where documents live]
|
v
[Checking tickets]
|
v
[Worked example] --> [Exercise EX061]
Learning outcomes
You will (1) write clear procedures for plugin installation and updates; (2) document safety rules; (3) keep documents current; (4) make them easy to follow.
16.1 The installation procedure
One page: confirm the request in a ticket; check the plugin is maintained; download from the official source only; verify the hash or signature from the vendor's site; take a backup; install with correct permissions; check headers and error logs; record version and hash in the ticket. Each step answers one Ferncroft gap: the official source and hash replace the mirror, the permissions step prevents a writable plugin folder, and recording the version feeds the inventory. The backup step comes from Grace's question about broken updates in the contained lab, so every installation can be rolled back.
16.2 The update procedure
Similar steps, plus checking change notes for breaking changes and a rollback plan. Change notes reveal breaking changes such as the renamed setting that broke alder-dental's contact form. Reading them before updating lets the technician apply the setting at once rather than discovering it through a customer complaint. The rollback plan names the backup to restore and who decides to restore it. The update procedure also repeats the hash or signature check, exactly as for a first installation of the same plugin.
16.3 Safety rules
Work only within ticket scope; never install from mirrors; never disable a control to fix an error; use synthetic data in tests; report anything unexpected to the duty supervisor. Each of these safety rules comes from a case met earlier in this course. Scope comes from the Ferncroft ticket, the mirror ban from the changed download, and the rule against disabling controls from troubleshooting. The rule on synthetic test data comes from the contained labs and the test copies. Reporting to the duty supervisor covers anything unexpected that no rule describes.
16.4 Writing clearly
Numbered steps, one action per step, and the reason for important steps in a short note. New technicians test the procedure by following it exactly. One action per step makes it obvious where a technician stopped or skipped. The short reasons help with judgement when something unexpected happens, such as the vendor publishing a signature instead of a hash. Testing by a new technician finds places where experienced staff fill gaps without noticing. Edits from those tests are recorded in the procedure's history.
16.5 Keeping current
Each document has an owner and review date; incidents and verification failures trigger updates. The signature gap found by a new technician shows how incidents and tests feed updates: the procedure gained a short part on checking vendor signatures. A named owner makes sure updates happen, and the review date catches documents that no incident has touched. The change history at the bottom of the procedure shows each update with its date and reason. Verification failures also trigger a check of whether the procedure missed a step.
16.6 Where documents live
Procedures sit in the support knowledge base linked from the ticket templates. Linking procedures from ticket templates puts them in front of technicians at the moment they need them. A technician opening an installation ticket sees the installation procedure and the mandatory fields for version, hash source and computed hash. Documents kept elsewhere are easily forgotten when a technician is working under time pressure. The knowledge base keeps one current version of each procedure, so technicians never follow a superseded copy saved locally on a desktop.
Checking tickets
Each month Grace samples ten installation tickets to see whether the version, hash source and computed hash were recorded. The first sample finds two tickets missing the hash source. The fields are made mandatory in the ticket form, and the next sample is complete.
Version history
Each procedure keeps a short change history at the bottom, showing what changed, when and why, so technicians can see recent updates.
Worked example
A new technician follows the installation procedure for the first time and stops at "verify the hash": the vendor publishes a signature, not a hash. Tomás adds a short section on checking vendor signatures and links the vendor's instructions.
Synthetic case. Procedures are synthetic.
Errors and limits
A procedure nobody follows is a false comfort; check tickets show the steps were done.
Exercises
- EX061 — Install steps. List four installation steps. Rubric: 3 = ticket, official source, verify, backup, permissions, record; 2 = three; 1 = one; 0 = none.
- EX062 — Safety rule. Name two safety rules. Rubric: 3 = scope; no mirrors; no disabling; synthetic tests; 2 = one; 1 = vague; 0 = none.
- EX063 — Testing documents. How is a procedure tested? Rubric: 3 = new technician follows it exactly; 2 = partial; 1 = vague; 0 = none.
- EX064 — Signature gap. What gap did the new technician find? Rubric: 3 = vendor uses signature not hash; 2 = partial; 1 = vague; 0 = none.
Synthesis
Clear, tested procedures make safe work routine.
Continue studying — chapter 16 of 18
← Chapter 15 (draft) · Course chapter index · Chapter 17 (draft) →