Chapter 16 — Technical documentation and safety
Lesson map
Lesson 16 published. Map, example, EX052.
flowchart TD
N0["Learning outcomes and connection"]
N1["16.1 The documents a technician owns"]
N2["16.2 Safety comes first and belongs to operations"]
N3["16.3 Transient devices and media"]
N4["16.4 Secrets and sensitive information"]
N5["16.6 Practical activity"]
N6["Chapter synthesis"]
N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> N6
N6 --> EX["Worked example"]
EX --> Q["Exercise EX052"]
Logical drawing
flowchart LR
N0["Learning outcomes and connection"]
N1["16.1 The documents a technician owns"]
N2["16.2 Safety comes first and belongs to operations"]
N3["16.3 Transient devices and media"]
N4["16.4 Secrets and sensitive information"]
N5["16.6 Practical activity"]
N6["Chapter synthesis"]
N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> N6 --> Q["EX052"]
[Learning outcomes and connection]
|
v
[16.1 The documents a technician owns]
|
v
[16.2 Safety comes first and belongs to operations]
|
v
[16.3 Transient devices and media]
|
v
[16.4 Secrets and sensitive information]
|
v
[16.6 Practical activity]
|
v
[Chapter synthesis]
|
v
[Worked example] --> [Exercise EX052]
Learning outcomes and connection
After this chapter you should be able to:
- write technical documents that another technician can execute safely: work instructions, troubleshooting logs, change records and as-built configuration records;
- integrate physical and process safety into technical work: permits, isolation, the authority of operations, and stop conditions;
- control transient devices — laptops and removable media taken to sites — so they do not carry malware or data between zones;
- keep secrets out of documents.
Chapters 1–15 produced findings, changes and evidence. This chapter is about the documents that make that work repeatable and safe, and about the safety rules that override any technical plan.
16.1 The documents a technician owns
| Document | Purpose | Must contain |
|---|---|---|
| Work instruction | Lets a competent colleague perform a task correctly | Preconditions, numbered steps with expected results, stop conditions, rollback, who to call |
| Troubleshooting log | Records an investigation as it happens | UTC times, four labels (observed, inferred, done, open), evidence references |
| Change record | Authorizes and records a change | Before/after, reason, tests (Chapter 11), rollback, window, approver, verifier |
| As-built record | States what is actually configured | Versions, configuration digests (Chapter 14), deviations from design and their approval |
Write steps as imperative actions with an observable result: "Run sshd -T | grep -i passwordauthentication; expect passwordauthentication no." A step without an expected result cannot be checked, and a document that cannot be checked will drift from reality.
16.2 Safety comes first and belongs to operations
In a water works, a substation or a hospital plant room, the people responsible for the physical process have authority over it. A technician's work there starts with their permission and stops at their request. Practical rules:
- Permits and isolation: work on or near process equipment follows the site's permit-to-work and isolation procedures; a security task does not exempt you.
- Protection and safety systems are never touched by security work: protection relays in a substation, safety instrumented systems, medical gas alarms.
- Inform before acting: the control room knows when you start, what you are doing and when you finish.
- Stop conditions are written into every work instruction (Chapter 5) and honoured immediately.
NIST SP 800-82 Rev. 3 discusses the relationship between OT security and safety (SP 800-82 Rev. 3); the UK NCSC Cyber Assessment Framework treats the operator's understanding of its essential functions as a foundation for security (NCSC CAF).
16.3 Transient devices and media
A laptop that visits stations, the control centre and the corporate office is a bridge across every zone. Controls a technician can apply:
- dedicated engineering laptops that never join the corporate network or the internet;
- a known-good image, updated and scanned at a controlled point before each site visit;
- removable media only from a controlled pool, scanned before use, with a log of where each item has been;
- no personal devices on control networks;
- a record of every connection made at a site (which port, which device, when).
The CISA performance goals list controls on removable media and on device configuration (CISA CPGs).
16.4 Secrets and sensitive information
Documents must not contain passwords, private keys, API tokens or one-time codes. Write "credential from vault entry kw-rtu-eng" instead of the credential. Network diagrams, register maps and firewall exports of critical infrastructure are sensitive: store them with access control, share them on a need-to-know basis, and remove them from tickets that go to suppliers. This book prints a few fake values only because they are fake.
The vault entry name can safely appear in a change ticket, because it tells an authorised engineer where to look without revealing anything an outsider could use. Real register maps and firewall exports deserve the same care as credentials, since together they describe how a station can be changed and from where.
16.5 Worked example: a work instruction (synthetic)
WI-KW-07 — Export KW-04 RTU configuration for drift baseline. Preconditions: change record CHG-2219 approved; Kestrel Water control room informed; engineering laptop ENG-L3 scanned today (record in the media log). Steps: (1) at 10:00 local, call the control room; record the operator's name. (2) On ENG-L3, open the vendor tool in read-only mode; expected: status bar shows "Online — read only". (3) Export the configuration to KW04-20261013.cfg; expected: file size between 40 and 60 kB. (4) Run sha256sum KW04-20261013.cfg; record the digest in CHG-2219. (5) Disconnect; inform the control room. Stop conditions: any alarm at KW-04; tool requests to switch to "online edit"; operator request. Rollback: none needed (read-only), but if any write is suspected, inform operations immediately and open an incident. Evidence: file, digest, call times.
16.6 Practical activity
Write a work instruction for the KW-04 router change from EX052, including preservation, the change, positive and negative tests, rollback and stop conditions. Ask someone else to read it and list every step where they would have to guess.
Include preservation of the router's configuration before the change, positive and negative tests afterwards, rollback steps and stop conditions that include any KW-04 alarm. Ask a colleague to mark every step where they would have to guess; those steps need an expected result or a screenshot of the vendor tool. Keep the reviewed copy with the change record.
16.7 Common errors and limits
- Steps without expected results.
- Documents that contain credentials or are shared too widely.
- Treating a site visit as an IT task and skipping the permit or the control-room call.
- One laptop for everything.
-
Documentation written after the work, from memory.
-
Leaving the rollback for a fw-01 rule change out of the site procedure, so a failed change has no tested way back.
- Putting credentials or full firewall exports into a widely shared ticket.
- Skipping the permit or the control-room call because the task looks like ordinary IT.
- Using one laptop for corporate, control-centre and site work.
- Writing the document from memory after the work.
Exercises — chapter 16
EX061 — Repair a work instruction. Objective: make steps executable. Inputs: "Log into the RTU (password Kestrel2024!) and check settings. Fix anything wrong. Tell ops when done." Steps: list the defects and rewrite. Expected evidence: defect list and rewritten instruction. Rubric: 3 = removes the credential (and recommends rotating it, since it has been written down), adds preconditions, read-only mode, expected results, stop conditions, informs operations before, replaces "fix anything" with a change record; 2 = most; 1 = cosmetic; 0 = none.
EX062 — Transient device policy. Objective: control a bridge across zones. Inputs: one engineer uses the same laptop for email and for station work. Steps: write a short technical policy and the transition plan. Expected evidence: policy and plan. Rubric: 3 = dedicated engineering laptops with a controlled image, no corporate or internet use, pre-visit check, media pool and log, connection record; transition that preserves the current laptop's project files after scanning; 2 = policy without transition; 1 = "be careful"; 0 = none.
EX063 — Safety boundaries. Objective: recognize what is out of bounds. Inputs: during a substation visit you find a protection relay with a default web password. Steps: state what you do and do not do, and how you record it. Expected evidence: short procedure. Rubric: 3 = do not log in or change it; record observation (device, time, how noticed); report to the Kestrel Grid protection engineer and the KVROC security lead; protection engineers decide and act; sensitive finding handled on need-to-know basis; 2 = right actions, weak record; 1 = changes the password; 0 = none.
EX064 — As-built record. Objective: document reality. Inputs: fw-01 after the EX038 fix and hist-02 after CHG-2207. Steps: draft an as-built record with versions, digests (placeholders allowed), deviations and approvals. Expected evidence: one-page record. Rubric: 3 = states actual configuration, includes digests and where they are stored, lists open deviations (REQ-3/4 before fix) with approvals or tickets, dated and signed; 2 = no deviations; 1 = copies the design; 0 = none.
Chapter synthesis
Good technical documents are executable and checkable: numbered steps with expected results, stop conditions, rollback and evidence. Safety and the authority of operations override every technical plan; protection and safety systems are out of bounds. Laptops and media that move between zones need their own controls, and secrets never belong in documents.
Continue studying — chapter 16 of 18
← Chapter 15 · Course chapter index · Chapter 17 →
Continue to the next authored lesson.