Chapter 14 — Simple documentation

Lesson map

Lesson 14 published. Map, example, EX053.

flowchart TD
  N0["Learning outcomes"]
  N1["14.1 Dictionary entries"]
  N2["14.2 A short procedure"]
  N3["14.3 Testing documents"]
  N4["14.4 Finding documents"]
  N0 --> N1 --> N2 --> N3 --> N4
  N4 --> EX["Worked example"]
  EX --> Q["Exercise EX053"]

Logical drawing

flowchart LR
  N0["Learning outcomes"]
  N1["14.1 Dictionary entries"]
  N2["14.2 A short procedure"]
  N3["14.3 Testing documents"]
  N4["14.4 Finding documents"]
  N0 --> N1 --> N2 --> N3 --> N4 --> Q["EX053"]

[Learning outcomes]
    |
    v
[14.1 Dictionary entries]
    |
    v
[14.2 A short procedure]
    |
    v
[14.3 Testing documents]
    |
    v
[14.4 Finding documents]
    |
    v
[Worked example] --> [Exercise EX053]

Learning outcomes

You will (1) write a data dictionary entry; (2) write a short procedure; (3) keep documents easy to find.

14.1 Dictionary entries

Marta writes dictionary entries for the passenger counts file. For each field she records the name, what it means in plain words, the format, allowed values and where it comes from. For boardings she writes: number of passengers getting on during the trip, whole number from zero to one hundred and twenty, recorded by door sensors. She checks each entry with Mr. Hughes. She notes that clear definitions stop people guessing what fields mean when they build reports. He suggests two small corrections.

14.2 A short procedure

Marta writes a procedure for the monthly authority file: run the missing counts check, fix or note problems, prepare the file from the template, check totals against the monthly report, get Mr. Hughes's approval and upload through the portal. Each step is numbered and names who does it. She keeps the language plain and adds what to do if the portal is unavailable, which happened once during the course. Mr. Hughes approves the procedure and asks that it be used every month by whoever prepares the file.

14.3 Testing documents

Marta asks a classmate to prepare a practice authority file using only her procedure. The classmate gets stuck at the totals check, because the procedure does not say which report to compare with. Marta adds the report name and location. The classmate then finishes without help. Mr. Osei explains that testing documents with someone new shows where steps that seem obvious to the writer are missing. Marta records the change and the reason in the procedure's history section, so that later readers can see how the document improved over time.

14.4 Finding documents

Marta stores the dictionary, procedures and scripts in one shared folder with a contents page listing each document, its owner and the date it was last checked. Mr. Hughes asks staff to use the contents page rather than searching through emails. Marta learns that documents only help if people can find them quickly, and that dates show whether a document is still likely to be correct. Marta checks the contents page every quarter during her placement and updates the dates of documents she has reviewed, flagging any she cannot confirm.

Worked example

Marta writes dictionary entries checked with Mr. Hughes, a numbered authority file procedure with a portal fallback, tests it with a classmate who finds a missing report name and stores documents with a dated contents page.

Synthetic case. Documents are synthetic.

Errors and limits

Procedures tested only by their writers miss obvious-seeming steps.

Exercises

• EX053 — Boardings definition. How is boardings defined?
  Show marking criteria

  Rubric: 3 = passengers getting on, whole number 0–120 from door sensors;; 2 = partly correct;; 1 = partial;; 0 = none.
• EX054 — Procedure gap. Where did the classmate get stuck?
  Show marking criteria

  Rubric: 3 = the totals check;; 2 = partly correct;; 1 = vague;; 0 = none.
• EX055 — Contents page. What does the contents page list?
  Show marking criteria

  Rubric: 3 = each document, owner and last checked date;; 2 = all;; 1 = some;; 0 = none.
• EX056 — Portal fallback. What extra case did the procedure cover?
  Show marking criteria

  Rubric: 3 = the portal being unavailable;; 2 = partly correct;; 1 = vague;; 0 = none.