◇ 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 Audiences"]
  N2["5.2 Diagrams"]
  N3["5.3 Trade-off tables"]
  N4["5.4 Plain language"]
  N5["Writing a design decision record"]
  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 Audiences"]
  N2["5.2 Diagrams"]
  N3["5.3 Trade-off tables"]
  N4["5.4 Plain language"]
  N5["Writing a design decision record"]
  N6["Synthesis"]
  N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> N6 --> Q["EX013"]

[Learning outcomes]
    |
    v
[5.1 Audiences]
    |
    v
[5.2 Diagrams]
    |
    v
[5.3 Trade-off tables]
    |
    v
[5.4 Plain language]
    |
    v
[Writing a design decision record]
    |
    v
[Synthesis]
    |
    v
[Worked example] --> [Exercise EX013]

Learning outcomes

You will (1) write design documents for mixed audiences; (2) draw clear network diagrams; (3) present trade-offs.

5.1 Audiences

Kofi's work will be read by council IT staff, managers and examiners. Each needs different detail. Managers need the problem, the decision and the cost; engineers need addressing, rules and procedures; examiners need method and evidence. He plans each document by asking who will read it and what they must decide.

Different readers need different things from the same design. Council managers want cost, risk and disruption in plain terms; operations staff need exact steps and rollback plans; auditors need evidence that controls exist and are checked. Writing one document that tries to serve all three usually serves none, so engineers prepare a short summary, a technical design and a separate evidence record.

5.2 Diagrams

A good network diagram shows zones, the controls between them and the direction of permitted flows, using a legend. Kofi draws a logical diagram of zones and policy separately from a physical diagram of sites and links, because mixing them makes both unreadable.

Kofi's logical diagram marks each Ashcombe zone as a labelled box and draws every permitted flow as an arrow that points from the side allowed to initiate it. It should omit detail that does not help the reader's decision, such as every cable, while keeping what does, such as where the firewall sits. Dating each diagram and keeping it with the design prevents people from trusting an outdated picture.

5.3 Trade-off tables

Design choices are presented as tables of options against criteria: security, cost, complexity and operational effort. Each cell has a short justification, so readers can disagree with a judgement rather than the whole table.

A trade-off table lists options as rows and criteria as columns, such as cost, security benefit, operational effort and disruption. Filling every cell forces the engineer to consider each option fairly, and stating the evidence behind each score makes the comparison checkable. Readers can then disagree with a specific cell rather than with the whole recommendation, which makes review discussions far more productive.

5.4 Plain language

Terms like segmentation are explained once in plain words: dividing the network so a problem in one part cannot easily spread to others.

Plain language means short sentences, familiar words, and defining any technical term on first use. Instead of writing that inter-VLAN routing will be restricted via ACLs, write that the network will stop guest devices from reaching staff computers. Readers who are not engineers make funding and approval decisions, so if they misunderstand the design, even an excellent technical plan may not be adopted. Testing a draft on a non-specialist colleague quickly reveals unclear passages.

Writing a design decision record

For each significant choice, Kofi writes a short decision record: the context, the options considered, the decision and its consequences. Records are numbered and never deleted; if a decision changes, a new record supersedes the old one and links to it. This gives the council a history of why the network looks the way it does, which is valuable when staff change. It also helps examiners follow the reasoning in his thesis, because each design element can be traced to a recorded decision rather than reconstructed afterwards.

Worked example

Kofi's one-page summary for managers states the problem (guest malware reaching servers), the proposal (six zones with default-deny policy) and the decision needed (budget for two firewalls).

Synthetic case. Documents are synthetic.

Errors and limits

Diagrams without legends or direction arrows are often misread.

Exercises

Synthesis

Clear documents and diagrams let each audience make its decisions.

Continue studying — chapter 05 of 50

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