Exercises — Chapter 33: Writing for Engineering

Writing is learned by writing. These exercises ask you to produce and revise engineering text—requirements, test cases, design rationale—not to pick letters. Difficulty is marked ⭐ (warm-up) to ⭐⭐⭐⭐ (extension).

Selected solutions and rubrics: appendices/answers-to-selected.md. Where a task is open-ended, a self-assessment rubric is given here instead of an answer.

Part A — Analyze This ⭐

Read each statement as the engineer who must build it and the tester who must verify it. Identify what's broken, and name the specific failure (untestable, compound, modal mush, design-in-requirement, normative/informative blur, orphaned).

A1. "The system shall be highly available and performant." — How many requirements are hiding here, and which words are untestable?

A2. "The dashboard should load fast, and it must be visually appealing, and ideally it would support dark mode." — Find the compound structure and the three different obligation strengths buried in it.

A3. "The system will encrypt data." — Is "will" a requirement, a prediction, or a description? Why is that ambiguity a problem, and what one change fixes it?

A4. "REQ-042. The system shall use a PostgreSQL database with a connection pool of 20." — What's wrong with putting this in a requirements document, and where does it belong?

A5. "Note: the API gateway should rate-limit requests to protect downstream services." — Two distinct problems (hint: one is about normative vs. informative; one is about testability). Name both.

A6. "REQ-099. The device shall be lightweight and approximately 200 g." — Why is "approximately 200 g" a missing specification rather than a modest one? What does a manufacturer actually need?

A7. A test case reads: "Expected result: the feature works as intended." — Why does this expected result verify nothing? What would two testers do differently with it?

A8. A hazard entry reads: "The high-voltage section could be dangerous. Technicians should be careful." — List the four things a well-formed hazard entry has that this one is missing.

A9. Spot the ambiguity in this spec excerpt. Below is a short excerpt from a (fictional) requirements document for a building's automated door system. Find every flaw you can—untestable words, compound requirements, modal mush, design baked into a requirement, normative/informative blur, and any orphaned or untraceable statement. Mark each one and name the failure.

Door Control System — Requirements (excerpt) 3.1 The door shall open quickly when a person approaches. 3.2 The door should be safe and must not close on anyone, and it will use an infrared sensor to detect obstructions. 3.3 The system shall handle high traffic and remain responsive during busy periods. 3.4 Note: the door must comply with all relevant accessibility regulations. 3.5 The door may have a manual override, and emergency egress is important.

Part B — Revise This ⭐⭐

Rewrite each into a proper engineering requirement (or set of requirements). Give each a sensible ID, make it atomic, choose the correct RFC 2119 keyword, and make it testable (value + condition + an implied or stated verification method). Where one statement hides several, split it.

B1. "The mobile app should have good battery life and shouldn't drain the phone too much in the background."

B2. "The login system needs to be secure and prevent unauthorized access, and it should lock out attackers after too many tries."

B3. "The report-generation feature must be reasonably quick even for large datasets, and it would be nice if it didn't time out."

B4. "The sensor should work in most weather conditions and survive being dropped occasionally."

B5. "The checkout flow must be intuitive and easy, and the system should handle payment failures gracefully."

B6. "The backup process will run periodically and keep enough history, and it should be possible to restore from it."

B7. (The flagship rewrite.) "The system should be fast." Rewrite it as a single, fully-formed, testable SHALL requirement. Then write the one-line verification method (which of Test/Inspection/Demonstration/Analysis, and what you'd actually do). This is the chapter's signature transformation—make it exemplary.

B8. A line in a spec reads: "The system uses a message queue to handle load (this is required)." Untangle the normative content from the informative content: write the testable requirement and the separate, clearly-labeled informative note.

Part C — Write This ⭐⭐–⭐⭐⭐

Produce the document the scenario calls for. Aim for publishable engineering prose—precise, traceable, no weak words.

C1. A requirements set. Choose a system you understand (a smart thermostat, a parking-payment app, a file-sync tool, a coffee machine with a timer). Write six requirements: two functional, two non-functional (one performance, one security or reliability), and two error-handling. Each must have a unique ID, be atomic, use a correct RFC 2119 keyword (include at least one SHALL, one SHOULD, and one MAY), and be testable. After each, add a one-line verification method.

C2. A traceability matrix. For the six requirements from C1, build a small traceability matrix with columns: Requirement ID · Source (the need it traces to) · Verification method · Test case ID. Then write one sentence per blank you find (or "no blanks—every requirement is sourced and verified").

C3. A test case. Pick one of your C1 requirements and write a full test case: Test case ID, the requirement ID it verifies, preconditions/setup, numbered steps (imperative, one action each), expected result (specific and measurable), and an unambiguous pass/fail criterion. A second tester should be able to run it and reach the same verdict.

C4. A design-doc "alternatives considered" section. For a design decision you understand (which database, which architecture, which algorithm, which material), write the Why (the forcing constraint), the chosen approach, and two alternatives considered with the specific reason each was rejected. The reader is a future maintainer asking "why did they do it this way?"

C5. A hazard entry. For any system with a real hazard (a battery, a heater, a moving part, a chemical, a high-voltage section), write a structured hazard entry: Hazard · Cause · Effect · Severity/Likelihood · Control (as a SHALL, traced to a test) · Residual risk. No "be careful."

C6. A manufacturing work-instruction step. Write one work-instruction step for an assembly action you can picture (seating a connector, applying an adhesive, torquing a fastener, installing a filter). Include the required tools/materials, a correctly-placed caution if there's a hazard, one action per numbered sub-step, exact values with tolerances, and an in-line verification ("Verify: …"). Then state how it improves on a prose version ("attach the part securely").

C7. A short specification excerpt, done right. Rewrite the entire A9 door-system excerpt as a clean, properly-formed requirements section: every requirement atomic, ID'd, testable, with a correct RFC 2119 keyword; the design detail moved to a clearly-labeled informative note (or deleted); the regulatory requirement pointing at a specific (named or placeholder) standard so it can trace. Add a one-line "Definitions" preamble stating that the keywords follow RFC 2119. Aim for the kind of excerpt that would survive an adversarial reading.

Part D — Synthesis & Critical Thinking ⭐⭐⭐

D1. Translate for three readers. Take this requirement: "The system shall return search results within 500 ms at the 95th percentile under a load of 1,000 concurrent users." Now write the same commitment (a) as a sentence in a customer-facing product summary (no jargon, no percentiles—what the customer actually experiences), (b) as a line in an engineer's design doc (what design constraint it imposes), and (c) as a test report entry after the test ran and measured p95 = 612 ms (state the failure honestly, with the number). Notice how audience (Chapter 2) reshapes the same fact three ways.

D2. Find the flaw. A spec contains: "REQ-017. The system shall be secure. REQ-018. The system shall encrypt sensitive data. REQ-019. The system should follow security best practices." All three are about security. Critique the set: which is untestable, which overlaps, which uses the wrong keyword, and how would you replace all three with a small set of genuinely testable security requirements?

D3. The over-specified requirement. A requirement reads: "The system shall store user sessions in a Redis cache with a 30-minute TTL, replicated across three nodes." Argue both sides: when is this level of implementation detail correctly in a requirement, and when is it a design decision that has wrongly migrated into the requirements document? What's the test for deciding?

D4. Why precision, really? The chapter claims engineering precision is "self-defense" against adversarial reading, not pedantry. In a paragraph, connect this to Chapter 13's standard for a Results section ("a rival who disagrees would still accept every sentence") and Chapter 38's coming theme that clarity is an ethical responsibility. Where do the three ideas converge?

D5. The cost gradient. The chapter argues the cheapest place to fix an engineering error is in the sentence, before anyone builds. Take a real-or-plausible example (a misread requirement, an ambiguous tolerance, an untested "should") and trace what it would cost to fix at four stages: in the requirements review, during design, during construction, and after the product shipped. What does this imply about how much effort a requirements review deserves?

Part M — Mixed Practice (Interleaved) ⭐⭐–⭐⭐⭐

These mix this chapter with earlier ones, so you have to choose the right tool—not just apply the most recent one.

M1. (Ch 33 + Ch 22) You're writing setup instructions for an internal tool and the requirement that governs the setup time. Write (a) one requirement ("the setup process SHALL complete within…") and (b) the first three numbered steps of the procedure a new hire follows. Note which document each belongs in and why the two are different genres for different readers.

M2. (Ch 33 + Ch 4) A requirements document opens with twelve pages of background before the first requirement. Apply Chapter 4's structure principles: where should the actual requirements live for the engineer who's scanning to find the ones that affect their component, and what belongs up front versus demoted? Sketch the reorganized table of contents.

M3. (Ch 33 + Ch 3) Take this requirement and apply both Chapter 3 (cut bloat, free the verb) and Chapter 33 (make it testable): "It is necessary that the system be capable of the provision of a response to user queries in a manner that is timely and does not result in undue delay." Two passes—first cut it to a clean sentence, then make it a testable SHALL.

M4. (Ch 33 + Ch 13) You ran a test and the result was a marginal pass (the requirement said ≤ 500 ms; you measured p95 = 498 ms). Write the test-report entry applying Chapter 13's Results discipline (report the observation neutrally, with the number, no spin) and a separate one-sentence note flagging the thin margin for the ship decision. Why must the observation and the flag be separate?

M5. (Ch 33 + Ch 7) Three versions of one obligation: "The system may encrypt passwords," "The system should encrypt passwords," "The system shall encrypt passwords." Explain, in the register of Chapter 7 (word choice carries weight), exactly what each communicates to the implementer—and argue which one is correct for passwords and why the wrong keyword here is a real safety error, not a style nitpick.

M6. (Ch 33 + Ch 9, advanced) A non-functional requirement concerns a relationship best shown visually (e.g., "response time SHALL stay under 500 ms as concurrent users rise from 100 to 1,000"). Decide whether the requirement should be prose or include a figure, and—separately—how the test report should present the result (a latency-vs-load chart with the 500 ms threshold drawn in). Write the figure's interpretive caption (Chapter 9 discipline) for the test-report chart.

Part E — Extension ⭐⭐⭐⭐ (optional; Deep Dive track)

E1. Audit a real spec. Find a publicly available specification or requirements document (an open hardware project's spec, an open-source project's requirements, a public RFC, an API contract). Audit a one-page excerpt: flag every weak word, every compound requirement, every modal-mush verb, every orphaned requirement, and every place normative and informative text blur. Then rewrite three of the worst into proper requirements. Report what fraction were genuinely testable as written.

E2. The whole loop. For one feature, write the complete chain and show the traceability end to end: a stakeholder need → a requirement (with ID, RFC 2119 keyword, testable) → a design decision (the how, with one rejected alternative) → a test case (verifies the requirement) → a test-report entry (with a plausible measured number). One page. The point is to feel how each document hands off to the next and how the requirement ID threads through all of them.

E3. Standards reconnaissance (no inventing numbers). Without fabricating any standard numbers, write a half-page for a new engineer joining your (real or hypothetical) field, explaining: which kinds of standards govern documents (requirements specs, safety cases, compliance) in that field, how to find out which specific ones apply to their work, and why those standards mostly codify the disciplines in this chapter. Cite only sources you can verify (RFC 2119 is fair game); for anything you're unsure of, say "your team will name the specific standard" rather than guessing.

Self-Assessment Rubric (for the open-ended tasks: B7, C1–C6, D-series, E-series)

Score each piece against these. Aim to satisfy all six.

The single best self-check on any requirement you write: could someone build this, and could someone else prove whether the thing they built satisfies it? If either answer is no, revise.