Chapter 16 — Technical documentation and safety
Lesson map
Lesson 16 published. Map, example, EX061.
flowchart TD
N0["Learning outcomes"]
N1["16.1 Purpose of documentation"]
N2["16.2 Writing procedures"]
N3["16.3 Safety in procedures"]
N4["16.4 Keeping documents current"]
N5["Synthesis"]
N0 --> N1 --> N2 --> N3 --> N4 --> N5
N5 --> EX["Worked example"]
EX --> Q["Exercise EX061"]
Logical drawing
flowchart LR
N0["Learning outcomes"]
N1["16.1 Purpose of documentation"]
N2["16.2 Writing procedures"]
N3["16.3 Safety in procedures"]
N4["16.4 Keeping documents current"]
N5["Synthesis"]
N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> Q["EX061"]
[Learning outcomes]
|
v
[16.1 Purpose of documentation]
|
v
[16.2 Writing procedures]
|
v
[16.3 Safety in procedures]
|
v
[16.4 Keeping documents current]
|
v
[Synthesis]
|
v
[Worked example] --> [Exercise EX061]
Learning outcomes
You will (1) write clear technical documents; (2) include safety and rollback; (3) keep documents current.
16.1 Purpose of documentation
Documentation lets others understand and safely change systems. Amina writes three kinds: reference documents describing the design (zones, flows, rules), procedures describing how to do tasks (runbooks), and records describing what happened (change and incident logs). Each has an owner and a review date. For a small organisation, documentation is often the only defence against losing knowledge when a person leaves, so it must be written for someone who was not involved. Amina tests each document by asking a classmate to use it.
16.2 Writing procedures
A good procedure states when to use it, prerequisites, steps, expected results at each step, what to do if a step fails and how to roll back. Amina writes the procedure for renewing the VPN gateway certificate this way and tests it in the lab. She uses short numbered steps and avoids assuming knowledge. Where a step could disrupt service, she marks it clearly and states the safe time to perform it, such as outside office hours. She reviews it with Rosa before use.
16.3 Safety in procedures
Technical work can disrupt services or expose data. Amina includes safety notes: save the current configuration before changing it, confirm the change window with Rosa, notify staff, and stop and roll back if a check fails. Procedures never include passwords or keys; they point to where credentials are stored. Including safety steps routinely means they are followed even under time pressure, when people are most likely to skip them. Each safety step has a tick box, so skipped steps are visible when the completed procedure is filed.
16.4 Keeping documents current
Documents decay when systems change and nobody updates them. Amina adds "update documentation" as a required step in the change procedure, so a change is not complete until documents match. She also schedules a quarterly review where Rosa skims each document and confirms it is accurate. Outdated documentation is worse than none, because people trust it; regular review keeps trust justified. Each document shows its last review date at the top, so readers can judge how far to trust it, and documents not reviewed for six months are flagged in Rosa's weekly report.
Worked example
Amina's certificate renewal procedure has twelve steps, two safety notes and a rollback section, and passes a lab test.
Synthetic case. Documents are synthetic.
Errors and limits
Procedures that include passwords become sensitive documents that leak credentials.
Exercises
- EX061 — Documentation kinds. Name the three kinds of documentation. Rubric: 3 = reference, procedures, records;; 2 = two;; 1 = one;; 0 = none.
- EX062 — Procedure elements. List four elements of a good procedure. Rubric: 3 = when, prerequisites, steps, expected results, failure handling or rollback;; 2 = three;; 1 = fewer;; 0 = none.
- EX063 — Credentials in documents. Where should procedures refer for credentials? Rubric: 3 = to where they are stored, never include them;; 2 = storage;; 1 = include them;; 0 = none.
- EX064 — Change completion. When is a change complete? Rubric: 3 = when documentation matches;; 2 = documentation updated;; 1 = when applied;; 0 = none.
Synthesis
Clear, safe, current documentation preserves knowledge and protects services.
Continue studying — chapter 16 of 18
← Chapter 15 (draft) · Course chapter index · Chapter 17 (draft) →