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 Runbooks"]
  N2["16.2 Safety and ethics rules"]
  N3["16.3 Keeping it 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 Runbooks"]
  N2["16.2 Safety and ethics rules"]
  N3["16.3 Keeping it current"]
  N4["Synthesis"]
  N0 --> N1 --> N2 --> N3 --> N4 --> Q["EX061"]

[Learning outcomes]
    |
    v
[16.1 Runbooks]
    |
    v
[16.2 Safety and ethics rules]
    |
    v
[16.3 Keeping it current]
    |
    v
[Synthesis]
    |
    v
[Worked example] --> [Exercise EX061]

Learning outcomes

You will (1) write runbooks for the reporting service; (2) include safety and ethics rules; (3) keep documentation current.

16.1 Runbooks

Priya writes runbooks for triage, verification holds, the weekly depot check and seasonal account setup. Each runbook states its purpose, steps, tools, expected results and what to do if something goes wrong. She uses numbered steps and screenshots. She tests each runbook by watching the second team member follow it without help, then fixes steps that caused hesitation. Runbooks let the service continue when the person who built it is absent or has moved on. Each runbook has a version number.

16.2 Safety and ethics rules

Priya includes rules in the documentation: never send simulated phishing without approval from the operations manager and staff representatives; never use lures about pay, health or job security; report results only in aggregate; never use reporting or click data in disciplinary or performance processes; and use test accounts and synthetic messages for any testing. She cites NIST SP 800-50r1 and the ENISA culture guidelines as background. Writing these rules down protects staff from well-meant but harmful experiments. The operations manager signs them.

16.3 Keeping it current

Documentation decays as systems change. Priya adds a review date to every page and a line at the top saying who owns it. She sets a calendar reminder for quarterly review. When the network change incident happened, she updated three pages within a day. She explains to Tom that outdated documentation can be worse than none, because people trust it, and that ownership and review dates are what keep documents useful over time. The IT lead adopts this practice. Owners confirm reviews.

Worked example

Priya writes tested runbooks, records ethics rules for any simulation or testing and sets owners and review dates.

Synthetic case. Documentation is synthetic; SP 800-50r1 and the ENISA guidelines are real.

Errors and limits

Reviews get skipped. Rules need enforcing.

Exercises

• EX061 — Runbook test. How were runbooks tested? Rubric: 3 = a colleague followed them unaided;; 2 = walkthrough;; 1 = vague;; 0 = none.
• EX062 — Banned lures. Which lures are banned? Rubric: 3 = pay, health or job security;; 2 = distress;; 1 = vague;; 0 = none.
• EX063 — Data rule. Where must reporting and click data never be used? Rubric: 3 = disciplinary or performance processes;; 2 = HR;; 1 = vague;; 0 = none.
• EX064 — Outdated danger. Why can outdated documentation be worse than none? Rubric: 3 = people trust it;; 2 = misplaced trust;; 1 = vague;; 0 = none.

Synthesis

Documentation includes steps, ethics rules and ownership so the service stays safe and current.

Continue studying — chapter 16 of 18

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