Chapter 16 — Technical documentation and safety

Chapter 16 — Technical documentation and safety

Lesson map

Lesson 16 published. Map, example, EX061.

flowchart TD
  N0["Learning outcomes"]
  N1["16.1 Writing clearly"]
  N2["16.3 Keeping documents current"]
  N3["Synthesis"]
  N0 --> N1 --> N2 --> N3
  N3 --> EX["Worked example"]
  EX --> Q["Exercise EX061"]

Logical drawing

flowchart LR
  N0["Learning outcomes"]
  N1["16.1 Writing clearly"]
  N2["16.3 Keeping documents current"]
  N3["Synthesis"]
  N0 --> N1 --> N2 --> N3 --> Q["EX061"]

[Learning outcomes]
    |
    v
[16.1 Writing clearly]
    |
    v
[16.3 Keeping documents current]
    |
    v
[Synthesis]
    |
    v
[Worked example] --> [Exercise EX061]

Learning outcomes

You will (1) write clear technical documents; (2) include safety and scope limits; (3) keep documents current.

16.1 Writing clearly

Aiko writes documents for different readers: runbooks for technicians, a short overview for the manager and a one-page guide for counter staff. Each starts with its purpose and audience. Runbooks use numbered steps with expected results. She avoids jargon or explains it once. Mr Kowal reviews her drafts and asks her to test each runbook by having another trainee follow it. Two steps confuse the trainee and she rewrites them. Clear documentation lets the library operate safely when Aiko is not there, which is the real test of any technical work.

16.2 Safety and scope limits

Each document states what it covers and what it does not. Runbooks warn where a step could affect live borrowers and say when to stop and escalate. For example, the node restart runbook says never to restart two nodes at once and to escalate if the remaining nodes are not healthy. Documents describe defensive tasks only and contain no instructions that could be used to misuse the system. Including limits protects people who follow the documents under pressure, when it is easy to go further than intended.

16.3 Keeping documents current

Documents become outdated when systems change. Aiko adds a review date and owner to each, and links documents to change tickets so that a change prompts a review of affected documents. After the deposit service update she finds two runbooks referring to an old command and updates them. She keeps a change history at the end of each document. Mr Kowal explains that an out-of-date runbook can be more dangerous than none, because people trust it and follow wrong steps confidently.

Worked example

Aiko's runbooks are tested by another trainee, warn never to restart two nodes at once and are linked to change tickets for review.

Synthetic case. The documents are synthetic.

Errors and limits

Out-of-date runbooks are trusted and followed even when their steps are wrong.

Exercises

• EX061 — Runbook test. How are runbooks tested? Rubric: 3 = another trainee follows them;; 2 = peer follows;; 1 = not tested;; 0 = none.
• EX062 — Restart warning. What does the restart runbook warn? Rubric: 3 = never restart two nodes at once;; 2 = one at a time;; 1 = restart all;; 0 = none.
• EX063 — Review trigger. What prompts a document review? Rubric: 3 = a linked change ticket;; 2 = system change;; 1 = vague;; 0 = none.
• EX064 — Outdated danger. Why can outdated runbooks be dangerous? Rubric: 3 = people trust and follow wrong steps;; 2 = false trust;; 1 = they are not;; 0 = none.

Synthesis

Clear, limited and current documentation lets others operate a system safely.

Continue studying — chapter 16 of 18

← Chapter 15 (draft) · Course chapter index · Chapter 17 (draft) →