Chapter 05 — Engineering communication

Chapter 05 — Engineering communication

Lesson map

Lesson 05 published. Map, example, EX009.

flowchart TD
  N0["Learning outcomes and connection"]
  N1["5.1 Requirements as testable statements"]
  N2["5.2 Traceability"]
  N3["5.3 Diagrams and audience"]
  N4["Chapter synthesis"]
  N0 --> N1 --> N2 --> N3 --> N4
  N4 --> EX["Worked example"]
  EX --> Q["Exercise EX009"]

Logical drawing

flowchart LR
  N0["Learning outcomes and connection"]
  N1["5.1 Requirements as testable statements"]
  N2["5.2 Traceability"]
  N3["5.3 Diagrams and audience"]
  N4["Chapter synthesis"]
  N0 --> N1 --> N2 --> N3 --> N4 --> Q["EX009"]

[Learning outcomes and connection]
    |
    v
[5.1 Requirements as testable statements]
    |
    v
[5.2 Traceability]
    |
    v
[5.3 Diagrams and audience]
    |
    v
[Chapter synthesis]
    |
    v
[Worked example] --> [Exercise EX009]

Learning outcomes and connection

After this chapter you can (1) rewrite vague claims as testable requirement statements; (2) maintain a traceability table from need to test; (3) draw a context diagram that names owners and trust boundaries; and (4) write risk notes that state assumptions and residual risk for the right audience. It prepares Chapters 16, 21 and 48.

5.1 Requirements as testable statements

A good requirement is necessary, unambiguous, verifiable and owned. "The platform will enable rapid response" fails all four. "When an analyst submits a containment request for a single user account, the platform shall present it to an approver within 60 seconds in 99% of requests measured over 30 days" is verifiable. Use "shall" for requirements, "should" for goals and name the verification method: test, analysis, inspection or demonstration. The NASA Systems Engineering Handbook gives a widely used treatment of requirement quality and verification methods.

5.2 Traceability

A trace table links each stakeholder need to requirements, design elements, tests and results. Its value appears during change: when the approval chain changes, you know which tests to rerun. A requirement without a test is a hope; a test without a requirement is either missing a requirement or wasted effort.

In the HVSS brief, a trace row for R3 would link the emergency-containment need to the emergency_contain state of Chapter 2, a test that confirms retrospective approval within 60 minutes, and the latest test result. When the response manager changes that window, the row shows which test must be rerun.

5.3 Diagrams and audience

A context diagram shows the system as one box, its external actors and data flows, and the trust boundaries crossed. Name owners on every external element. Write for the reader: a service owner needs consequences and decisions; an engineer needs interfaces and limits; an auditor needs evidence and accountability. One document can serve all three only if it is layered: a one-page summary, then detail. For HVSS the context diagram would show the identity provider, endpoint agent and client tenants as external actors, each with a named owner.

5.4 Worked example (synthetic): rewriting an HVSS design brief

The synthetic brief says: "The new response platform will automatically detect and stop attacks quickly, keep all evidence and integrate with everything. Security will own it." Problems: "automatically stop" conflicts with delegated authority (Chapter 10); "quickly" is unmeasured; "all evidence" is unbounded and conflicts with privacy minimisation; "everything" names no interfaces; "Security" is a department, not an accountable person. Rewrite (extract):

Unresolved assumptions recorded as risk notes: the cloud provider's log delivery delay is unknown; retention conflicts with the privacy officer's 180-day default and needs a decision.

5.5 Errors and limits

• Unmeasurable adjectives (fast, robust, seamless).
• Requirements that prescribe a product instead of a property.
• Owners named as teams.
• Assumptions hidden in prose rather than listed.

The original HVSS brief in the worked example commits all four of these errors. "Quickly" and "stop attacks" are unmeasurable adjectives, "integrate with everything" names no interface, "Security will own it" names a department, and the 180-day privacy default against 400-day retention was hidden until the rewrite exposed it. Each rewritten requirement in the table answers one of those defects with a number, an interface, an owner or a recorded risk note.

Exercises — chapter 05

EX009 — Rewrite. Objective: produce testable requirements. Inputs: "Recovery must be fast and reliable, and the platform must always be available during incidents." Steps: write three requirements with verification method and owner role; list two assumptions. Expected evidence: table and list. Rubric: 3 = measurable, owned, verifiable, assumptions explicit; 2 = one weak item; 1 = still vague; 0 = none.

EX010 — Trace gap. Objective: find gaps. Inputs: the R1–R4 table. Steps: add a "test ID" and "result" column with plausible synthetic entries and identify one requirement that cannot be verified by test alone and why. Expected evidence: table and explanation. Rubric: 3 = identifies R4 (400-day retention needs analysis/inspection of configuration and periodic sampled verification, not a single test) or an equally well-argued case; 2 = partial; 1 = attempt; 0 = none.

Chapter synthesis

Engineering communication turns aspiration into commitments that can be checked. Write testable, owned requirements; trace them to tests; layer documents for their readers; and put assumptions in the open where they can be challenged.

Continue studying — chapter 05 of 50

← Chapter 04 · Course chapter index · Chapter 06 →

Continue to the next authored lesson.