OpenCyber Academy
Technical · Chapter 14 · English
Course code: OCA-048Chapter 14: OCA-048-C014

Chapter 14 — Simple documentation

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

Lesson map

Lesson 14 published. Map, example, EX053.

flowchart TD
  N0["Learning outcomes"]
  N1["14.1 Why document"]
  N2["14.2 Writing instructions"]
  N3["14.3 Change records"]
  N4["14.4 Storing documents"]
  N0 --> N1 --> N2 --> N3 --> N4
  N4 --> EX["Worked example"]
  EX --> Q["Exercise EX053"]

Logical drawing

flowchart LR
  N0["Learning outcomes"]
  N1["14.1 Why document"]
  N2["14.2 Writing instructions"]
  N3["14.3 Change records"]
  N4["14.4 Storing documents"]
  N0 --> N1 --> N2 --> N3 --> N4 --> Q["EX053"]

[Learning outcomes]
    |
    v
[14.1 Why document]
    |
    v
[14.2 Writing instructions]
    |
    v
[14.3 Change records]
    |
    v
[14.4 Storing documents]
    |
    v
[Worked example] --> [Exercise EX053]

Learning outcomes

You will (1) write simple instructions others can follow; (2) keep records of changes; (3) store documents where they can be found.

14.1 Why document

Mr. Doyle is Westfield's only IT person. When he is on holiday, the support company and centre managers need to know how things are set up. Chloe learns that simple documentation, written clearly, lets others help when the usual person is away. Mr. Appiah explains that documentation is a security control, because mistakes happen when people guess how systems work and change the wrong setting. Chloe asks Mr. Doyle which tasks the support company most often phones him about while he is away. He names three, and she decides to document those first, because they would help the most people.

14.2 Writing instructions

Chloe writes step-by-step instructions for three tasks: setting up a new tablet, resetting a till staff code and checking that the nightly backup ran. Each has a title, purpose, numbered steps with screenshots and what to do if something goes wrong. She asks a centre manager to follow the tablet instructions. The manager gets stuck at one step, so Chloe adds a missing screenshot. She learns that the best test of instructions is someone else using them. The manager then completes it without help.

14.3 Change records

Chloe starts a simple change log for Westfield: date, what changed, why, who made the change and how to undo it. She enters the router password change, the folder permission changes and the guest wireless separation. Mr. Doyle finds it useful when a centre manager asks why she can no longer see the invoices folder. The log answers the question in seconds. She adds a column showing whether each change was tested afterwards, and fills it in for the changes made so far. Mr. Doyle decides to keep using the log after her placement, and asks the support company to add their changes to it too.

14.4 Storing documents

Chloe stores the instructions and change log in a shared folder that managers and the support company can open, but not customers or till accounts. She avoids writing passwords in documents and refers to the password manager instead. She adds a date and owner to each document. Mr. Appiah notes that documents without dates leave readers unsure whether they are still correct. She creates an index document listing every instruction, its purpose, owner and date, so a reader can find the right one quickly. Mr. Doyle checks the folder permissions and confirms that only managers and the support company can open it.

Worked example

Chloe writes and tests three sets of instructions, starts a change log that answers a manager's question and stores dated documents without passwords.

Synthetic case. Documents are synthetic.

Errors and limits

Writing passwords into documents exposes them to every reader.

Exercises

Worked answers

EX053. Resetting a till staff code.

EX054. A centre manager.

EX055. Why a centre manager could no longer see invoices.

EX056. So readers know whether they are still correct.