Chapter 5 — Engineering communication

Chapter 5 — Engineering communication

Lesson map

Lesson 05 published. Map, example, EX013.

flowchart TD
  N0["Learning outcomes"]
  N1["5.1 Decision records"]
  N2["5.2 Reviewable diagrams"]
  N3["5.3 Explaining trade-offs"]
  N4["Synthesis"]
  N0 --> N1 --> N2 --> N3 --> N4
  N4 --> EX["Worked example"]
  EX --> Q["Exercise EX013"]

Logical drawing

flowchart LR
  N0["Learning outcomes"]
  N1["5.1 Decision records"]
  N2["5.2 Reviewable diagrams"]
  N3["5.3 Explaining trade-offs"]
  N4["Synthesis"]
  N0 --> N1 --> N2 --> N3 --> N4 --> Q["EX013"]

[Learning outcomes]
    |
    v
[5.1 Decision records]
    |
    v
[5.2 Reviewable diagrams]
    |
    v
[5.3 Explaining trade-offs]
    |
    v
[Synthesis]
    |
    v
[Worked example] --> [Exercise EX013]

Learning outcomes

You will (1) write architecture decision records; (2) draw diagrams others can review; (3) explain security trade-offs to non-specialists.

5.1 Decision records

Daniel introduces the architecture decision record, a short document stating the context, the decision, the options considered, the consequences and the date. Sofia writes one for a simple choice: whether fare validators should store a full deny list of blocked cards or query the server each time. The record explains the options, chooses local deny lists with hourly updates for offline resilience and states the consequence that a newly blocked card may work for up to an hour. Decision records let future engineers understand why a design looks the way it does instead of guessing or repeating old debates.

5.2 Reviewable diagrams

Sofia learns that a diagram is for review, not decoration. A good data-flow diagram shows processes, data stores, external entities, data flows and trust boundaries, the notation Shostack (2014) uses for threat modelling. Every arrow is labelled with what flows and over what protocol. Every boundary is drawn where trust changes, such as between a bus and the depot network. She redraws a cluttered vendor diagram into a clean one with a legend and a version number. Reviewers can then point to exactly the element they question, which makes reviews faster and more precise.

5.3 Explaining trade-offs

Corvia's finance director asks why the fare system cannot block stolen cards instantly. Sofia writes a half-page explanation without jargon: validators work offline on vehicles, they update their lists every hour, and instant blocking would require constant connectivity that buses do not have. She states the risk, a stolen card used for at most an hour, and the cost of reducing it. Daniel praises the explanation because it states the trade-off plainly and lets the director decide whether more frequent updates are worth the extra data costs, rather than hiding the decision inside technical language.

Worked example

Sofia writes a decision record on deny lists, redraws a vendor diagram with labelled flows and boundaries and explains the one-hour blocking window to the finance director.

Synthetic case. Decisions, diagrams and the director are synthetic; Shostack (2014) is real.

Errors and limits

Decision records go stale if not updated when decisions change. Plain explanations can omit edge cases that matter.

Exercises

• EX013 — ADR fields. List the fields of an architecture decision record. Rubric: 3 = context, decision, options, consequences, date;; 2 = four;; 1 = two;; 0 = none.
• EX014 — Boundary placement. Where should a trust boundary be drawn in a data-flow diagram? Rubric: 3 = where trust changes, such as between a bus and the depot network;; 2 = trust change;; 1 = anywhere;; 0 = none.
• EX015 — Blocking window. What risk did Sofia state to the finance director? Rubric: 3 = a stolen card may be used for up to an hour;; 2 = one hour;; 1 = vague;; 0 = none.

Synthesis

Clear records, reviewable diagrams and plain trade-off explanations make security decisions visible and accountable.

Continue studying — chapter 05 of 50

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