◇ OpenCyber Academy
Engineering · Chapter 5 · English

Chapter 5 — Engineering communication

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 5 — Engineering communication

Lesson map

Lesson 05 published. Map, example, EX013.

flowchart TD
  N0["Learning outcomes"]
  N1["5.1 The engineer's documents"]
  N2["5.2 Communicating uncertainty"]
  N3["5.3 Documenting AI components"]
  N4["5.4 Audiences"]
  N5["5.5 Structure and traceability"]
  N6["Synthesis"]
  N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> N6
  N6 --> EX["Worked example"]
  EX --> Q["Exercise EX013"]

Logical drawing

flowchart LR
  N0["Learning outcomes"]
  N1["5.1 The engineer's documents"]
  N2["5.2 Communicating uncertainty"]
  N3["5.3 Documenting AI components"]
  N4["5.4 Audiences"]
  N5["5.5 Structure and traceability"]
  N6["Synthesis"]
  N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> N6 --> Q["EX013"]

[Learning outcomes]
    |
    v
[5.1 The engineer's documents]
    |
    v
[5.2 Communicating uncertainty]
    |
    v
[5.3 Documenting AI components]
    |
    v
[5.4 Audiences]
    |
    v
[5.5 Structure and traceability]
    |
    v
[Synthesis]
    |
    v
[Worked example] --> [Exercise EX013]

Learning outcomes

You will (1) write clear technical documents (requirements, design notes, test reports, incident summaries); (2) communicate uncertainty and risk honestly; (3) tailor messages to engineers, managers and regulators; and (4) document AI components with model cards and datasheets.

5.1 The engineer's documents

Requirements say what a system must do and must not do. Design notes explain choices and alternatives. Test reports state what was tested, how, results and limits. Incident summaries state what happened, impact, cause and actions. Each has a reader with a decision to make; write for that decision.

Writing for a decision changes what goes first. A manager deciding whether to deploy TrackEye needs the risk and the options on page one; a tester repeating the evaluation needs the method in full. Sam opens each document with one sentence naming its reader and the decision it supports, which also shows him what can be left out.

5.2 Communicating uncertainty

Never write "the model is secure". Write "under the tested conditions (list), the false-negative rate was 2.1% (95% interval 1.6–2.7%); untested conditions include heavy snow and deliberate markings". Numbers with intervals and explicit conditions let readers judge for themselves. Separate facts (measured), assessments (your judgement) and recommendations.

The interval tells the reader how much the figure could move if the test were repeated with new data. Listing untested conditions is just as important, because readers otherwise assume the result covers them. Keeping facts, assessments and recommendations in separate paragraphs lets a reader who disagrees with a judgement still trust the measurements it rests on.

5.3 Documenting AI components

Model cards (Mitchell et al., arXiv:1810.03993) describe a model's intended use, out-of-scope uses, evaluation data, metrics broken down by relevant factors, and ethical considerations. Datasheets for datasets (Gebru et al., arXiv:1803.09010) describe motivation, composition, collection, preprocessing, uses, distribution and maintenance. Both make hidden assumptions visible to downstream engineers and auditors.

For TrackEye, the datasheet records that most training images came from daytime runs on standard-gauge track, which explains later weaknesses at dawn and on unfamiliar rail types. A downstream team planning to reuse the model can see that limitation before deploying it, rather than discovering it in service.

5.4 Audiences

Engineers need precise interfaces and failure modes. Managers need risk, cost and options. Regulators and auditors need traceable evidence linked to requirements. The same fact may appear in three forms.

The dawn false-negative problem shows the three forms. For engineers: false negatives rise to 9% between 05:00 and 07:00 at 60–80 km/h, with the test set named. For managers: dawn inspections miss more defects, a fix is under way, and an interim manual check is in place. For auditors: the finding, the requirement it affects, the test record and the corrective action, each with an identifier.

5.5 Structure and traceability

Number requirements (REQ-SEC-012) and refer to them from design notes and test reports so that anyone can trace a requirement to its evidence. Use tables for conditions and results, figures for trends, and short paragraphs for reasoning. Put the conclusion first and the method second for decision readers; reverse it for reviewers who must check the method. Version every document and keep a change log: an evaluation that was true for model v1.3 may be false for v1.4.

A change log entry records what changed, why, and which results it invalidates.

5.6 Worked example (synthetic NRS case)

Sam's first TrackEye test report said "works well in most conditions". The supervisor returned it. The revised version had a one-paragraph summary for managers ("dawn false negatives are 4.5× daytime; fix in progress; interim: second visual check at dawn"), a table by condition with intervals for engineers, and a model-card section stating out-of-scope uses (not validated for tram rails or snow).

The 4.5× figure is the dawn false-negative rate of 9% divided by the daytime 2%. The original sentence was not false, but it gave readers nothing to act on. The revision lets each reader find what they need without reading the rest.

5.7 Errors and limits

Absolute claims are tempting because they sound confident, but a single counterexample undoes them and with them the reader's trust. Mixed measurement and opinion makes it impossible to challenge one without the other. A model card describing version 1.3 attached to version 1.5 is worse than none, because readers rely on it; Sam ties each card to a model version and updates it in the same change that releases the model.

Exercises

Synthesis

Clear, honest communication — conditions, intervals, separated facts and recommendations, and documented models and datasets — is how engineering evidence reaches the people who decide.

Continue studying — chapter 05 of 50

← Chapter 04 (draft) · Course chapter index · Chapter 06 (draft) →