◇ OpenCyber Academy
Technical · Chapter 16 · English

Chapter 16 — Technical documentation and safety

Open, free learning for anyone who wants to protect people and technology. No account is required to read this text or its worked answers.

Chapter 16 — Technical documentation and safety

Lesson map

Lesson 16 published. Map, example, EX061.

flowchart TD
  N0["Learning outcomes"]
  N1["16.1 What to document"]
  N2["16.2 Runbooks"]
  N3["16.3 Plain writing"]
  N4["16.4 Safety"]
  N5["16.5 Review"]
  N6["16.6 Location"]
  N7["Documentation for auditors"]
  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 What to document"]
  N2["16.2 Runbooks"]
  N3["16.3 Plain writing"]
  N4["16.4 Safety"]
  N5["16.5 Review"]
  N6["16.6 Location"]
  N7["Documentation for auditors"]
  N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> N6 --> N7 --> Q["EX061"]

[Learning outcomes]
    |
    v
[16.1 What to document]
    |
    v
[16.2 Runbooks]
    |
    v
[16.3 Plain writing]
    |
    v
[16.4 Safety]
    |
    v
[16.5 Review]
    |
    v
[16.6 Location]
    |
    v
[Documentation for auditors]
    |
    v
[Worked example] --> [Exercise EX061]

Learning outcomes

You will (1) document configurations and procedures; (2) write for the next person; (3) keep safety boundaries.

16.1 What to document

Storage policy, exceptions, check scripts, alert runbook, partner sharing procedure. These are the documents a colleague would need if Tomás were away when an alert fired. The storage policy says what is required, the exceptions register says what is allowed and why, the scripts show how compliance is checked, and the runbook and sharing procedure say what to do. Each document links to the others at the points where their subjects meet. Each document names an owner and a review date six months ahead.

16.2 Runbooks

The alert runbook says what the alert means, how to check, how to revert and who to tell. For the public-access alert, the runbook says that a bucket outside the assets account has become public, how to confirm it in the console or logs, how to revert through the repository and whom to tell. After a colleague got stuck on 'revert via IaC', the runbook now gives the exact command and file path. The runbook is linked from the alert message itself, so it opens in one click.

16.3 Plain writing

Short sentences, numbered steps and no unexplained acronyms. The test is whether a colleague can follow a document without asking Tomás anything. Numbered steps let a reader keep their place during an alert, and spelled-out terms such as 'infrastructure as code' avoid confusion. Tomás rewrites any step that a reviewer had to ask about, rather than explaining it verbally and leaving the text unchanged. Each runbook step starts with a verb, such as 'check' or 'revert', so the action is clear. Acronyms like CI and IaC are spelled out at first use in each document.

16.4 Safety

Documents never include secret values or customer data. Examples use for secret values and synthetic bucket contents, as the labs do. A runbook copied into a ticket or shared with the insurer should never carry a credential or a customer's address. Reviewers check this specifically, and documents with real values are corrected and the exposed values rotated. Screenshots are checked as well, since they often capture values the text avoids. The documents also restate the course boundary: defensive checks only, and nothing tested outside the written scope.

16.5 Review

Grace reviews every document; a colleague follows each runbook once. Grace's review checks accuracy and safety, and the colleague's walk-through checks that the steps work in practice. The runbook test exposed the 'revert via IaC' gap, which a reading review had missed. Each review is recorded with a date, and documents are reviewed again at their six-month review date. Comments from readers go to the document's owner, who responds within a week. A runbook that has not been followed by a colleague is marked draft until it has.

16.6 Location

Documents live beside the code they describe. Keeping the runbook in the same repository as the alert code means a change to the alert and to its instructions appear in the same merge request. Reviewers can then see in one place whether the document still matches the code. Versioned with the code, the history also shows which procedure applied at any given date. Documents that are not tied to code, such as the exceptions register, live in the same repository's documentation folder.

Documentation for auditors

Auditors want to see policy, evidence that controls run and records of exceptions. Tomás organises the documentation so each policy rule links to its check, latest output and any exception. When Fairway's insurer asks about cloud storage controls after the incident, Grace answers with links in under an hour.

The documentation also records the incident review and actions, showing that lessons led to changes.

Writing style

Tomás uses headings that match questions readers ask, such as "What do I do when the alert fires?"

Diagrams

A single diagram shows where checks run and where alerts go.

Safety boundaries

The documents describe defensive checks only and state that testing outside scope is not permitted.

Ownership

Each document names an owner responsible for keeping it accurate and a review date six months ahead. Owners receive a reminder when the date arrives.

Feedback loop

Readers can comment on any document, and the owner responds within a week. Comments often reveal steps that seemed obvious to the writer but not to readers.

Worked example

A colleague following the runbook gets stuck on "revert via IaC". Tomás adds the exact command and the file path.

Synthetic case. Synthetic.

Errors and limits

Documents decay; give each a review date.

Exercises

Synthesis

Write for the next person and test the writing.

Continue studying — chapter 16 of 18

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