Chapter 5 — Engineering communication
Lesson map
Lesson 05 published. Map, example, EX013.
flowchart TD
N0["Learning outcomes"]
N1["5.1 Audiences"]
N2["5.2 Report structure"]
N3["5.3 Diagrams"]
N4["5.4 Uncertainty"]
N5["5.5 Responsible detail"]
N6["Written decisions"]
N7["Feedback"]
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 Report structure"]
N3["5.3 Diagrams"]
N4["5.4 Uncertainty"]
N5["5.5 Responsible detail"]
N6["Written decisions"]
N7["Feedback"]
N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> N6 --> N7 --> Q["EX013"]
[Learning outcomes]
|
v
[5.1 Audiences]
|
v
[5.2 Report structure]
|
v
[5.3 Diagrams]
|
v
[5.4 Uncertainty]
|
v
[5.5 Responsible detail]
|
v
[Written decisions]
|
v
[Feedback]
|
v
[Worked example] --> [Exercise EX013]
Learning outcomes
You will (1) write clear technical reports; (2) present security findings to mixed audiences; (3) use diagrams effectively; (4) communicate uncertainty.
5.1 Audiences
Engineers want detail, managers want decisions and impact, the public wants reassurance and facts. Kwame writes the same finding three ways.
For engineers: the tmpl version, the affected attributes and the upgrade path. For managers: the exposure period, whether data was affected and what the fix costs. For the public: that a flaw was found and fixed, and that no evidence of misuse was seen. The facts are the same in all three; only the detail and emphasis change. Kwame checks that none of the versions says anything another version contradicts.
5.2 Report structure
Summary, context, findings, evidence, recommendations, limitations. The summary fits in five lines.
The summary is written last but read first, and often it is the only part managers read. It must stand alone: what happened, what it means and what is recommended. The remaining parts support it for readers who need to check. Limitations come at the end but are never omitted, because a report that hides them loses credibility as soon as a reader finds one. Each finding links to its evidence, so a reviewer can follow any claim to its source without asking the author.
5.3 Diagrams
Kwame's dependency graph diagram made the tmpl surprise clear to managers in one glance.
The diagram showed tmpl two arrows away from ticket-web, which answered the question every manager asked: how did we not know? A diagram works when it shows one idea. Kwame removed packages unrelated to the finding, highlighted the path from ticket-web to tmpl, and labelled each arrow, so the picture could be understood without the report beside it. He also included the date of the graph, since dependencies change.
5.4 Uncertainty
"We have no evidence the flaw was used" is different from "the flaw was not used". Ingrid insists on accurate phrasing.
The first statement reports what was examined and what was found. The second claims knowledge the team does not have, since logs may not cover every request and an attacker may leave no trace. Readers make different decisions on each: the first may justify further monitoring, while the second suggests nothing more is needed. Accurate phrasing protects both the reader and the team.
5.5 Responsible detail
Reports about flaws avoid giving step-by-step misuse instructions; they describe the weakness, its effect and the fix.
Reports travel further than intended: they are forwarded, quoted and sometimes leaked. A description of the weakness and its fix lets readers act, while exploit steps help only attackers. Where engineers need technical detail to verify a fix, it goes in a restricted appendix with a list of who may read it. Kwame's reports describe the tmpl flaw as an escaping failure in certain attributes, without showing a working attack.
Written decisions
Important decisions are recorded in short decision records: context, options, choice, consequences. When Coastline decided to deploy security fixes outside the monthly release, the record explained the 11-day versus 30-day exposure comparison from chapter 1. New staff can read why the rule exists instead of guessing, and the team can revisit the decision if circumstances change. Kwame writes his first decision record about the digest check on the artifact mirror, keeping it to one page with a clear recommendation.
Feedback
Kwame asks two readers, one technical and one not, to read each report before it goes out. They mark anything unclear. Most of his early drafts used jargon such as "transitive dependency" without explanation; he now adds a short definition the first time a term appears.
Worked example
Kwame's summary for Coastline's board: "A third-party template component in ticket-web had a published flaw for 11 days before our fix was deployed. We found no evidence it was used. We have added automated checks so such components are found within a day." The board asks for a quarterly update.
Synthetic case. Reports are synthetic.
Errors and limits
Simplifying for managers must not change the meaning.
Exercises
- EX013 — Report sections. List the report sections. Rubric: 3 = summary, context, findings, evidence, recommendations, limitations; 2 = four; 1 = two; 0 = none.
- EX014 — Accurate phrasing. Why say "no evidence it was used"? Rubric: 3 = not the same as not used; 2 = partial; 1 = vague; 0 = none.
- EX015 — Responsible detail. What do reports avoid? Rubric: 3 = step-by-step misuse instructions; 2 = partial; 1 = vague; 0 = none.
Synthesis
Communicate to each audience accurately, with diagrams and honest uncertainty.
Continue studying — chapter 05 of 50
← Chapter 04 (draft) · Course chapter index · Chapter 06 (draft) →