Key Takeaways — Chapter 33: Writing for Engineering

A one-page summary card. Use it to re-ground before the quiz, or to review weeks later.

The one idea

A requirement that cannot be tested is not a requirement—it is a wish. In engineering the document comes before the thing: you write the requirement, then build to it, so a vague sentence doesn't merely confuse a reader—it gets the wrong thing built. The question is never "is this clear?" but "what test returns pass or fail on this, and would two engineers run the same test and get the same answer?" If you can't name the test, the requirement isn't finished.

🚪 Threshold concept: A requirement is a commitment that will be verified, not a description of what you want. Before you cross this, "the system should be fast" feels like a fine requirement—everyone knows what it means. After, you see it has no verification method, so it commits no one to anything and can be neither met nor violated. You start writing the test in your head as you write the requirement.

The core moves

• Make every requirement atomic, unambiguous, and testable. Atomic: one requirement per statement—split at every "and" that joins independent obligations. Unambiguous: exactly one reading—hunt the weak words (fast, robust, user-friendly, efficient, "approximately" with no tolerance). Testable: a named verification method exists—Test, Inspection, Demonstration, or Analysis—that returns pass/fail.
• The modal verb carries the obligation (RFC 2119, Tier 1). SHALL/MUST = absolute requirement (mandatory). SHOULD = strong recommendation you may deviate from only with a deliberate, documented reason. MAY = truly optional. Write the keywords in their defined sense; don't make everything SHALL (that prioritizes nothing); don't drift into modal mush ("will/should/ideally/encouraged"). Choosing the keyword forces you to decide how strong each obligation really is.
• Keep the levels in separate rooms. Normative (the binding SHALLs) separate from informative (explanation, rationale)—so a reader knows instantly whether a sentence is a commitment or a comment. And requirements (the what, the outcome to verify) separate from design (the how and why)—specify the outcome, leave the implementation to the designers.
• Traceability is the spine. Every requirement gets a stable ID and traces back to a source (a need—no source may mean gold-plating) and forward to a test case (no test means unverified). A traceability matrix makes both blanks visible; scan for them.
• Each document has its own discipline. Design docs record the why, especially the alternatives considered and why you rejected them (the section authors most often skip and maintainers most need). Test reports record the number, not just "PASS" (the margin is decision-relevant). Safety docs trace each hazard—hazard, cause, effect, control—to a verified control, plainly stated (the Challenger lesson: a buried risk is a lethal one). The engineering notebook is contemporaneous and honest about dead ends. Work instructions make the build repeatable across people and units (an exact value and tolerance, the pattern, the sequence, an in-line check).

The diagnostic

The threshold question, applied to every requirement: Could someone build this, and could someone else prove whether the thing they built satisfies it? If either answer is no, it's a wish—add the value, the condition, the tolerance, and the verification method until both answers are yes.

The cautionary tale

A search team shipped a feature built on "REQ-12: the system should be fast." The product owner meant "instant, as you type"; the engineers meant "under two seconds." Both signed off; both were certain they agreed. Six weeks of work hit the wall—not because the code was wrong, but because eleven untestable words carried two different products. Rewritten as testable SHALL statements (250 ms typeahead at p95, etc.), the disagreement that cost six weeks took fifteen minutes to resolve—on paper, before anyone built. (Case Study 1.) On a factory floor, the same vagueness ("fasten tightly") didn't fail once but on a population of units, in two opposite directions, until a missing tolerance was written down. (Case Study 2.)

The test to apply before you ship anything specifying a system

For every requirement: what test returns pass or fail on this—and would two competent engineers get the same answer?

If there's no such test, you've written a wish, not a requirement. Add the number, the condition, and the verification method until there is.

Themes this chapter surfaced: #5 structure-serves-the-reader (the spec is organized for the engineer who builds and the verifier who checks; traceability) · #3 clarity-is-not-the-enemy-of-precision (the whole chapter—precision is the deliverable, and "approximately" without a tolerance is a missing spec) · #6 every-sentence-earns-its-place (atomic requirements; cut the weak words) · #2 audience-is-everything (the reader may be a tester, an auditor, or an adversary). Theme #1 (writing-is-thinking) runs underneath: writing the requirement testably, and the design doc's "alternatives considered," is how you do the thinking the vague version let you skip.

Threshold concept: A requirement that cannot be tested is not a requirement—it is a wish.

Back to: Chapter 33 · Exercises · Quiz · Further Reading