Chapter 5 — Engineering communication
Lesson map
Lesson 05 published. Map, example, EX013.
flowchart TD
N0["Learning outcomes"]
N1["5.1 Audiences"]
N2["5.2 Structure"]
N3["5.3 Diagrams"]
N4["5.4 Incident summaries"]
N5["5.5 Trade-offs"]
N6["5.6 Review"]
N7["Writing incident summaries"]
N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> N6 --> N7
N7 --> EX["Worked example"]
EX --> Q["Exercise EX013"]
Logical drawing
flowchart LR
N0["Learning outcomes"]
N1["5.1 Audiences"]
N2["5.2 Structure"]
N3["5.3 Diagrams"]
N4["5.4 Incident summaries"]
N5["5.5 Trade-offs"]
N6["5.6 Review"]
N7["Writing incident summaries"]
N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> N6 --> N7 --> Q["EX013"]
[Learning outcomes]
|
v
[5.1 Audiences]
|
v
[5.2 Structure]
|
v
[5.3 Diagrams]
|
v
[5.4 Incident summaries]
|
v
[5.5 Trade-offs]
|
v
[5.6 Review]
|
v
[Writing incident summaries]
|
v
[Worked example] --> [Exercise EX013]
Learning outcomes
You will (1) write clear technical documents for different audiences; (2) structure design notes and incident summaries; (3) use diagrams effectively; (4) present trade-offs honestly.
5.1 Audiences
Rosa's platform team needs exact configuration changes; Solent's managers need risk and cost; the regulator needs evidence of controls. Elena writes one design note with a short summary for managers and detailed sections for engineers.
Each audience reads for a different purpose. Engineers need to know exactly what to change and how to test it; managers need to decide whether to fund and approve; regulators need confidence that controls exist and work. Writing one document with layered sections serves all three without forcing anyone to read what they do not need.
5.2 Structure
Context, problem, options, decision, consequences, open questions. This structure, common in architecture decision records, makes reasoning visible.
A fixed structure helps readers find what they want and helps writers spot what they forgot. Writing options before the decision shows the choice was considered, not assumed. Consequences include costs and risks, not only benefits. Open questions show what is still uncertain, so readers know where judgement may change later. Elena's first note runs to two pages, with the manager summary in the first paragraph.
5.3 Diagrams
A diagram of meterhub shows ingest, API, database and metrics pods, with arrows for allowed traffic. Trust boundaries are drawn as dashed lines. One diagram per question avoids clutter.
Arrows for allowed traffic make it obvious what should and should not talk. Dashed trust boundaries show where checks must happen. A diagram trying to show deployment, data flow and permissions at once becomes unreadable, so Elena draws separate diagrams for each question and labels each one with its purpose. Each diagram is dated.
5.4 Incident summaries
The key-leak summary states timeline, impact, cause, fixes and lessons, without blame and without guessing.
Blame shuts down honest discussion; people who fear blame hide details. Guessing replaces evidence with stories that may be wrong. The summary sticks to what is known, says what is not, and focuses on fixes that change the system, such as scanning images for secrets before they are published. Elena drafts the summary from the recorded timeline and asks the engineers involved to correct any errors before it circulates.
5.5 Trade-offs
Every option has costs. Elena writes "default-deny network policies will block undocumented traffic; we expect some breakage during rollout" rather than hiding it.
Admitting expected breakage builds trust and helps planning. If teams know default-deny policies will block undocumented traffic, they can prepare by documenting flows and watching closely during rollout. Hiding the cost would only mean surprise and frustration later, and a design that loses support at the first problem. Rosa agrees with Elena on a rollback plan for each expected problem.
5.6 Review
Documents are reviewed by an engineer and a non-engineer to check both clarity and accuracy.
An engineer checks that the technical content is correct; a non-engineer checks that the summary and reasoning make sense to someone outside the field. Each catches different problems. Elena asks a Solent operations manager to read her design note and rewrites two paragraphs that the manager found confusing. Reviewers' comments and Elena's responses are kept with the note, so later readers can see what changed and why.
Writing incident summaries
For the key-leak summary Elena writes short dated entries: when the image was built, when it was pushed, when the key was found, when it was revoked. Each entry cites a log or ticket. Readers can then check the facts, and the summary stays useful months later.
Presenting
Elena presents the design note to the platform team in ten minutes: one slide for the problem, one for each option with its cost, and one for the recommendation. Questions are recorded and answered in the next version of the note.
Worked example
Elena's first design note proposes three fixes. Rosa's manager reads only the summary and asks which fix matters most. Elena revises the summary to rank them with one sentence each on risk reduced and effort required.
Synthetic case. Documents are synthetic.
Errors and limits
Long documents without a summary are rarely read.
Exercises
- EX013 — Note structure. List the design note sections. Rubric: 3 = context, problem, options, decision, consequences, questions; 2 = four; 1 = two; 0 = none.
- EX014 — Trade-off honesty. How did Elena state a trade-off? Rubric: 3 = expect breakage during rollout; 2 = partial; 1 = vague; 0 = none.
- EX015 — Summary revision. What did the manager need? Rubric: 3 = ranked fixes with risk and effort; 2 = partial; 1 = vague; 0 = none.
Synthesis
Write for the reader and show trade-offs openly.
Continue studying — chapter 05 of 50
← Chapter 04 (draft) · Course chapter index · Chapter 06 (draft) →