◇ 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 Tickets"]
  N3["5.3 Design documents"]
  N4["5.4 Honest charts"]
  N5["5.5 Words for uncertainty"]
  N6["5.6 Case"]
  N7["Review before sending"]
  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 Tickets"]
  N3["5.3 Design documents"]
  N4["5.4 Honest charts"]
  N5["5.5 Words for uncertainty"]
  N6["5.6 Case"]
  N7["Review before sending"]
  N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> N6 --> N7 --> Q["EX013"]

[Learning outcomes]
    |
    v
[5.1 Audiences]
    |
    v
[5.2 Tickets]
    |
    v
[5.3 Design documents]
    |
    v
[5.4 Honest charts]
    |
    v
[5.5 Words for uncertainty]
    |
    v
[5.6 Case]
    |
    v
[Review before sending]
    |
    v
[Worked example] --> [Exercise EX013]

Learning outcomes

You will (1) write clear technical notes, tickets and design documents; (2) adapt communication to analysts, managers and customers; (3) present data honestly with tables and charts; (4) use precise language for uncertainty.

5.1 Audiences

Analysts need exact fields and times; managers need impact and decisions; customers need what happened and what to do. One incident produces several documents, each written for its reader.

Writing one document for all three fails each of them: analysts lose detail, managers drown in it, customers get jargon. Amara starts each piece by asking what the reader must do after reading it. That question decides what to include, from field names for the analyst to a single recommended decision for the manager.

5.2 Tickets

A good SOC ticket states what was observed, when (with time zone), on which assets, what was done, and what is still unknown. Knerler, Parker and Zimmerman (2022) emphasise clear communication as a SOC strategy in its own right.

Stating what is unknown is the part most often skipped, yet it tells the next shift where to look. A time without a zone forces a reader to guess, and a wrong guess can reorder the story. Assets should be named by identifiers the asset inventory uses, so other teams can find them without asking.

5.3 Design documents

Engineering changes, such as a new detection, need a short design document: problem, proposal, alternatives, risks, test plan and rollback.

Writing alternatives forces the author to show why the proposal beats other options, not just that it works. A test plan states how the detection will be shown to fire on the target behaviour and stay quiet on normal activity. Rollback explains how to remove the change quickly if it floods the queue after deployment. Paolo reviews each document before the rule goes live.

5.4 Honest charts

Charts must start axes at zero for counts, label units and time zones, and avoid smoothing away spikes that matter.

A count axis starting at 900 can make a rise from 950 to 1,000 look like a doubling. Unlabelled time zones can shift a spike into the wrong shift. Smoothing with a long moving average makes trend lines look tidy but can erase the very burst an incident chart is meant to show, so raw counts should appear alongside any smoothed line. Captions state the data source.

5.5 Words for uncertainty

"Confirmed", "likely" and "possible" should be used consistently. Amara's team defines them in a style guide so readers know how sure the writer is.

Without agreed meanings, one writer's 'likely' is another's 'possible', and a manager may act on a stronger claim than the evidence supports. The style guide links each word to the evidence expected: 'confirmed' needs direct evidence such as a log entry, 'likely' needs several consistent indicators, and 'possible' marks a lead not yet checked. The guide fits on one page.

5.6 Case

After the portal burst, Amara writes three items: the analyst ticket, a manager summary and a draft customer notice for account u5's owner, reviewed by Paolo and the communications team.

The ticket lists the failure counts, the network, u5's successful login time and session actions, with times in UTC. The manager summary gives the impact in two sentences and states what has already been done and the change now proposed. The customer notice explains in plain words that unusual sign-in activity was seen and what the customer should do.

Review before sending

Anything leaving the SOC is reviewed by a second person: one checks facts against the ticket, the other checks tone and clarity. For customer notices, the communications team approves the final wording, because a misleading notice can do more harm than the incident itself. Amara keeps the reviewed versions with the ticket.

Worked example

Amara's manager summary: "On Monday 10:05–10:06 UTC, about 600 login attempts from one network targeted customer portal accounts. One customer account was accessed successfully and has been locked; the customer has been contacted. No staff systems were affected. A rate-limit change is proposed."

Synthetic case. The incident and texts are invented.

Errors and limits

Clear writing cannot fix wrong facts; check figures against sources before sending.

Exercises

Synthesis

Communicate for each reader, with precise uncertainty and honest charts; clarity is part of SOC engineering.

Continue studying — chapter 05 of 50

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