Chapter 33: Writing for Engineering: Standards, Specifications, and Technical Requirements

"A specification is a contract between the people who want something and the people who will build it." — paraphrasing a common engineering maxim

Chapter Overview

A team of four engineers spent six weeks building a feature. They tested it, demoed it, shipped it. The customer rejected it. Not because it was broken—it did exactly what it did, reliably. They rejected it because the one-line requirement they had signed off on said "The system should respond quickly to user requests," and the engineers had read "quickly" to mean "under two seconds" while the customer had meant "instantly, like a desktop app." Both parties were certain they had agreed. Both were reading the same eleven words. The defect was not in the code. The defect was in the sentence—a sentence vague enough that two competent people could read opposite meanings into it and never discover the disagreement until six weeks of work hit the wall. This is the failure that engineering writing exists to prevent, and it is the most expensive kind of writing failure there is, because in engineering the words come first and the steel, silicon, and concrete follow. A bad sentence becomes a bad bridge, a recalled device, a feature built twice.

This chapter opens Part VII, where the same principles you've practiced for thirty-two chapters meet the specific conventions of particular fields. The principles do not change. Audience is still everything (Chapter 2). Structure still serves the reader (Chapter 4). Every sentence still has to earn its place (Chapter 3). What changes is the stakes and the conventions: engineering writing is read by people who will build from it, verify against it, certify it, and—when something fails—litigate over it. So the field has evolved a discipline of precision that can look pedantic from the outside (why does it matter whether you write "should" or "shall"?) and turns out, from the inside, to be the difference between a document that can be built and tested and one that cannot. You already met the doer's version of this in Chapter 22: instructions are a tool to be operated, not prose to be admired. Engineering documents extend that idea—they are tools to be built from and verified against, and the verification is the whole point.

Here is the threshold this chapter asks you to cross: a requirement that cannot be tested is not a requirement—it is a wish. "The system should be fast" is a wish; nobody can run a test that returns pass or fail on it. "The system shall return search results within 500 ms for 95% of queries under a load of 1,000 concurrent users" is a requirement, because there is exactly one way to read it and a test that decides it. Crossing that threshold reorganizes how you write every engineering sentence: you stop asking "is this clear?" and start asking "could someone build this, and could someone else prove whether the thing they built satisfies it?" By the end of this chapter, you will be able to take a vague, well-meaning requirement and rewrite it as a single, unambiguous, testable statement using the SHALL/SHOULD/MAY discipline that engineers have standardized precisely so this disagreement stops happening—and you'll recognize the documents that carry it: specifications, design docs, test plans, compliance records, the engineering notebook, and the work instructions that turn a design into a manufactured object.

In this chapter, you will learn to:

• Write a requirement that is atomic, unambiguous, and testable, with a measurable acceptance criterion.
• Use RFC 2119 keyword discipline (SHALL/MUST, SHOULD, MAY) to state the exact strength of every requirement, and keep normative text separate from explanation.
• Choose and structure the core engineering documents—requirements specification, design document, test plan and report, compliance documentation, the engineering notebook, and manufacturing work instructions.
• Build traceability so every requirement has an ID, a rationale, and a verification method, and nothing is orphaned.
• Audit a specification for the failures that recur—weak words, compound requirements, untestable claims, and "the system should be fast."

📕 Engineering/Science track: This is your core chapter for Part VII. The requirement-writing discipline in §33.2–33.4 is the foundation; treat the RFC 2119 keyword rules as non-negotiable vocabulary you'll use for the rest of your career. If you're in software, §33.5 (design documents) connects directly to Chapter 34's design docs and ADRs. If you're in hardware, mechanical, or systems engineering, pay special attention to §33.6 (test plans), §33.7 (safety and compliance), and §33.9 (manufacturing work instructions), which extend Chapter 22's procedural writing onto the factory floor.

33.1 Why Engineering Writing Is Different: The Document Comes First

Most writing describes something that already exists. A lab report (Chapter 13) documents an experiment you ran. A status update (Chapter 21) reports work you did. Even a tutorial (Chapter 26) describes a path someone can already walk. Engineering specification writing is different in a way that reorganizes everything: the document comes before the thing. You write the requirement, and then the engineers build to it. You write the test plan, and then the testers run it. The words are not a record of reality; they are the blueprint reality will be built from. That inversion is why a vague engineering sentence is so much more dangerous than a vague sentence anywhere else. A vague status update wastes a reader's minute. A vague requirement gets the wrong thing built.

Consider the cost gradient. A requirements defect caught while reviewing the requirements document costs almost nothing—you fix a sentence. The same defect caught during design costs more—you redo a diagram. Caught during construction, it costs a rebuild. Caught after the product ships, it costs a recall, a field patch, a lawsuit, or a fatality. The widely-cited pattern in engineering is that the cost of fixing a defect rises by roughly an order of magnitude at each stage it survives undetected. You do not need the exact multiplier to feel the force of it: the cheapest place to fix an engineering error is in the sentence, before anyone builds anything. That is what makes the writing matter. The requirements document is the last point at which an error is still just words.

Start with a failure, because the failure teaches the principle.

❌ Before (a requirement as it's often first written — fictional but realistic): The system should be fast and able to handle a reasonable number of users without significant slowdown. Error handling should be robust.

Read that as a stakeholder who wants a fast system, and it sounds like agreement. Read it as the engineer who has to build it and the tester who has to verify it, and it dissolves into questions with no answers. Fast—how fast, measured how, under what conditions? A reasonable number of users—is that ten, ten thousand? Significant slowdown—significant compared to what baseline? Robust error handling—robust against which errors, doing what when they occur? There is no test you can run that returns pass or fail. Two engineers will build two different systems and each will believe they met the spec. The sentence feels like a requirement because it's grammatical and on-topic, but it commits no one to anything checkable. It is a wish wearing the costume of a requirement.

Now the same intent, written as engineering requirements:

✅ After (testable requirements): - REQ-PERF-001. The system shall return search results within 500 ms at the 95th percentile, measured at the API boundary, under a sustained load of 1,000 concurrent users. - REQ-PERF-002. The system shall sustain 1,000 concurrent users with no more than 0.1% of requests returning a 5xx error over any 5-minute window. - REQ-ERR-001. On a failed database write, the system shall retry up to 3 times with exponential backoff, and if all retries fail, shall return HTTP 503 and log the failure with the request ID at ERROR level.

Why it's better: Each statement names a measurable quantity (500 ms, 1,000 users, 0.1%, 3 retries), a condition under which it's measured (95th percentile, at the API boundary, sustained load), and—crucially—a way to verify it. A tester can build a load test, run it, and report pass or fail with no judgment call. The word "should" became "shall," signaling these are mandatory, not aspirational. The one bloated sentence became three numbered requirements, each addressing one concern, each independently testable. Nobody can read REQ-PERF-001 two ways. That single property—one reading, testable—is what separates an engineering requirement from a wish, and it is the spine of this entire chapter.

🔄 Check Your Understanding A teammate writes a requirement: "The login page must load quickly and be user-friendly." Name the two distinct problems with this as an engineering requirement, and say which word is doing useful work and which words are doing none.

Answer

Problem 1 — it's not testable. "Quickly" has no number and no condition (load when? measured where? at what percentile?), and "user-friendly" has no definition you could verify at all—two reviewers would disagree about whether a given page is user-friendly. Problem 2 — it's compound: it bundles two unrelated requirements (load time and usability) into one statement, so it can't be tracked, tested, or marked pass/fail as a unit. The word "must" is doing useful work—it correctly signals the requirement is mandatory. The words "quickly" and "user-friendly" are doing none; they feel like specifications but commit no one to anything checkable. Fix: split into two requirements, give the load time a number and a condition, and replace "user-friendly" with the specific, testable behaviors you actually mean (e.g., "shall meet WCAG 2.1 AA," "shall require no more than two fields to log in").

A second thing that makes engineering writing distinct: someone hostile may read it. Not hostile in a personal sense, but a regulator auditing your compliance, an opposing expert witness after an accident, a customer's lawyer reading the contract you signed. Engineering documents are written to survive adversarial reading—the reading that hunts for the gap, the ambiguity, the unmet "shall." This is the same instinct as Chapter 13's standard for a Results section ("a rival who disagrees with your interpretation would still accept every sentence"), pushed further: an engineering spec should be written so that a motivated adversary cannot honestly claim it means something you didn't intend. Precision is not pedantry here. Precision is self-defense.

33.2 The Anatomy of a Requirement: Atomic, Unambiguous, Testable

A requirement is a statement of something the system must do or a quality it must have. A specification (often "spec") is the organized collection of requirements for a system. Most of an engineer's writing life is spent making individual requirements good, so it's worth knowing exactly what "good" means. A well-formed requirement has three properties, and the failure modes you'll see in real specs are almost always a violation of one of them.

Atomic — one requirement per statement. A requirement states one thing, so it can be tracked, tested, and marked pass or fail as a unit. The instant you write "and," check whether you've smuggled two requirements into one. The compound requirement is the most common defect in real specs, and it's poison for traceability: when half of "the system shall log the event and notify the administrator" is implemented and half isn't, what's the status of the requirement? Neither pass nor fail. Split it.

❌ Before (compound): The system shall encrypt all data at rest and in transit, and shall log all access attempts.

✅ After (atomic): - REQ-SEC-001. The system shall encrypt all data at rest using AES-256. - REQ-SEC-002. The system shall encrypt all data in transit using TLS 1.2 or higher. - REQ-SEC-003. The system shall log every access attempt (success and failure) with a timestamp, user ID, and source IP.

Why it's better: Three requirements that can each be tested, tracked, and assigned independently. The "before" couldn't be marked pass/fail when (as is common) two of the three were done and one wasn't. Splitting also forced a useful precision: "encrypt all data" became two different mechanisms (AES-256 at rest, TLS in transit) that a single sentence had blurred together.

Unambiguous — exactly one reading. This is the hardest and most important property, and it's where the famous weak words live. Certain words feel like they're saying something but leave the actual value to the reader's imagination. Hunt them down:

Each of these is the engineering cousin of Chapter 3's "so what?" test and Chapter 22's "vague condition" ("if everything looks good, proceed"). The cure is the same: name the value, the condition, the tolerance.

❌ Before: The device shall operate efficiently across a wide temperature range and shall be approximately 100 mm long.

✅ After: - REQ-THM-001. The device shall maintain rated performance (per REQ-PERF-010) across an operating temperature range of −20 °C to +60 °C. - REQ-DIM-001. The device length shall be 100 mm ± 0.5 mm.

Why it's better: "Efficiently" and "wide range" became a stated performance reference and an explicit temperature band that a thermal chamber can test. "Approximately 100 mm" became a value with a tolerance—and the tolerance is the requirement. A manufacturer can't build to "approximately"; they need to know whether a 101 mm part passes. In engineering, "approximately" without a tolerance is not modesty—it's a missing specification.

Testable (verifiable) — there exists a method that returns pass or fail. This is the threshold concept stated operationally. For every requirement, you must be able to answer: how would we verify this? If the answer is "we'd look at it and form an opinion," it's not a requirement yet. Engineers name four standard verification methods, and a good spec records which one applies to each requirement:

• Test — exercise the system and measure (run the load test; apply the voltage; drop the unit). The strongest evidence.
• Inspection — examine the item directly (check the part number; read the label; confirm the weld exists).
• Demonstration — operate the system and observe the behavior without instrumented measurement (show that the alarm sounds when the door opens).
• Analysis — use models, calculation, or simulation where testing is impractical (compute the worst-case thermal load; analyze the stress model). Used when you can't physically test every case.

If you cannot assign one of these four to a requirement, the requirement is not yet written. "The UI shall be modern" has no verification method—there's no test, inspection, demonstration, or analysis that decides "modern." That's the tell that you've written a wish.

🧩 Productive Struggle Before reading on, try to make this requirement testable: "The mobile app shall have good battery life." Don't just add a number at random—think about what's actually missing. What quantity? Measured under what activity? Over what duration? Compared to what? Write your version, then compare.

One good answer

The phrase "good battery life" is missing a measurable quantity, the activity during measurement, and the reference condition. A testable version names all three:

REQ-PWR-001. During continuous video playback at 50% screen brightness on the reference device (Model X, 4,000 mAh battery), the app shall consume no more than 8% battery per hour.

Now there's a test: charge the reference device, play video at the stated brightness for an hour, measure the drain. "Good" became 8%/hour under a named activity on a named device. Notice you had to specify the condition (brightness, device, activity), because battery drain is meaningless without it—the same lesson as Chapter 13's replicable Methods: a measurement without its conditions can't be reproduced or verified. There are other valid numbers; what makes it a requirement is that some number, some condition, and some method now exist.

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

How people think before crossing this threshold: a requirement is a description of what we want. If it captures the intent and reads clearly, it's a good requirement. "The system should be fast" feels like a perfectly good requirement—everyone knows what it means, everyone agrees, what more do you need? Clarity, in this view, is about being understandable.

How engineers think after crossing it: a requirement is a commitment that will be verified. 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?" "The system should be fast" fails not because it's unclear in spirit—you know roughly what it means—but because there is no test that decides it, so it commits no one to anything and can be neither met nor violated. Once you've crossed this threshold, you read every requirement looking for the verification method, and when you can't find one, you don't see a clear requirement that needs polish—you see a wish that isn't a requirement yet. You start writing the test in your head as you write the requirement, because if you can't imagine the test, you haven't finished the requirement.

This is why engineering specs look the way they do—numbered, quantified, conditioned, almost legalistic. It's not a love of bureaucracy. It's that every sentence has to survive the question how would we prove this?, and sentences that can't survive it get rewritten until they can.

[📍 Good stopping point — the requirement anatomy above is the heart of the chapter. The rest applies it to the specific documents.]

33.3 SHALL, SHOULD, MAY: The Vocabulary of Obligation (RFC 2119)

Here is a small, real, and genuinely useful piece of standardization. When you write a requirement, you are stating an obligation—and obligations come in strengths. Some things are mandatory: the system must do them or it fails to meet the spec. Some are recommended: do them unless you have a good reason not to. Some are optional: permitted, but not required. English has many words for these strengths, and that's the problem—"must," "shall," "will," "should," "ought to," "may," "can," "is encouraged to" all blur together, and a reader can't tell whether "the system will log errors" is a hard requirement or a casual description of expected behavior.

Engineering solved this by standardizing the vocabulary. The most widely used standard is RFC 2119 (a real document, "Key words for use in RFCs to Indicate Requirement Levels," from the Internet Engineering Task Force), and its conventions have spread far beyond internet protocols into systems, software, and hardware specs everywhere. RFC 2119 assigns precise meanings to a small set of keywords, and the convention is to write them in uppercase when you mean the defined, normative sense:

(A field note: MUST and SHALL mean the same thing in RFC 2119. By convention, internet and software protocol specs often prefer MUST, while systems-engineering, aerospace, and government/defense specs strongly prefer SHALL—to the point that in many hardware traditions, "SHALL" is the word for a binding requirement and "will" is reserved for statements of fact or intent about the environment, not obligations on the system. Pick the convention your field and your document use, then use it consistently. The discipline matters more than the choice.)

Why does this tiny vocabulary matter so much? Because the keyword tells the reader—and the contract, and the auditor—exactly how much room they have. Watch what changes when only the keyword changes:

• The system shall encrypt stored passwords. → Mandatory. Ship without it and you have failed the spec. A test that finds plaintext passwords is a defect of the highest severity.
• The system should encrypt stored passwords. → Recommended. You're expected to do it, but if you had an extraordinary, documented reason not to, you could still claim conformance. (You would also be making a serious security mistake—which is exactly why this should almost certainly be SHALL.)
• The system may encrypt stored passwords. → Optional. Doing it or not are both conformant. (For passwords, this is the wrong keyword—it signals encryption is take-it-or-leave-it, which it is not.)

Three sentences, one word different, three completely different contracts. The reader who knows RFC 2119 reads the keyword first—it's the load-bearing word in the sentence. This is the engineering analog of Chapter 7's lesson that word choice carries weight and Chapter 4's BLUF instinct (lead with what decides the reader's action): in a requirement, the modal verb is the decision.

❌ Before (mixed, ambiguous modals): The gateway will validate the certificate. It's important that it also checks the expiration date, and ideally it would reject self-signed certs. Logging is encouraged.

✅ After (RFC 2119 discipline): - REQ-TLS-001. The gateway SHALL validate the server certificate against the configured trust store. - REQ-TLS-002. The gateway SHALL reject any certificate whose expiration date has passed. - REQ-TLS-003. The gateway SHOULD reject self-signed certificates; if self-signed certificates are accepted, the configuration SHALL require an explicit administrator override. - REQ-TLS-004. The gateway SHALL log every certificate validation failure at WARN level with the certificate subject and the failure reason.

Why it's better: Every obligation now has an explicit, standardized strength. "Will validate" (was it mandatory? a prediction?) became a clear SHALL. "It's important that it also checks" became a SHALL with no wiggle room. "Ideally it would reject self-signed certs" became a SHOULD with a documented escape hatch (the override), which is exactly what SHOULD is for—a strong default you can deviate from deliberately and visibly. "Logging is encouraged" became a SHALL, because the team decided audit logs were actually mandatory; writing the keyword forced that decision into the open. The act of choosing the keyword forces you to decide how strong each obligation really is—a decision the vague "will/should/ideally/encouraged" original let everyone avoid.

A common beginner question: if SHALL is the strong one, why not make everything SHALL to be safe? Because a spec where everything is mandatory is a spec where nothing is prioritized, and it's brittle—every SHOULD you promote to SHALL is a constraint the implementer can't trade off even when the trade-off is obviously right. SHOULD exists precisely so you can say "this is the strong default; deviate only with reason." Reserve SHALL for what is genuinely non-negotiable, use SHOULD for strong recommendations with a deliberate escape hatch, and use MAY for true options. A spec that uses all three thoughtfully tells the reader far more than a wall of SHALLs.

🔍 Why Does This Work? Why does a standardized, uppercase keyword like SHALL communicate more reliably than a perfectly ordinary English sentence like "the system needs to encrypt passwords"? Think before reading on.

Because it removes the reader's need to infer strength from tone, and inference is where disagreements hide. "The system needs to encrypt passwords" could be read as an absolute requirement, a strong recommendation, or even a description of what the system happens to do—the strength lives in the reader's interpretation of "needs to," and two readers can interpret it differently without either noticing. A defined keyword collapses that interpretive space: SHALL has one agreed meaning, published in a standard both parties can point to, so there's nothing left to infer. The word stops being a matter of tone and becomes a matter of definition. This is the same mechanism as a legal term of art or an SI unit—a community agrees on an exact meaning for a token so that using the token transmits the meaning without loss. You're trading the warmth and flexibility of natural language for something engineering needs more: a word that means exactly one thing to everyone who reads it.

One more discipline that travels with RFC 2119: the distinction between normative and informative text. Normative text is the binding part—the actual requirements, the SHALLs and SHOULDs. Informative text is explanation, rationale, examples, background—helpful, but not itself a requirement. Good specs keep them visibly separate (a "Note:" prefix, a different formatting, a labeled "Rationale" block), so a reader knows instantly whether a sentence is a commitment or a comment. The danger of blurring them is real: an offhand explanatory sentence ("the system uses a cache to improve performance") can get read as a requirement ("the system shall use a cache"), locking in an implementation detail nobody meant to mandate. Write requirements in normative keywords; write everything else as clearly-labeled informative text. (This echoes Chapter 13's discipline of keeping Results separate from Discussion—observation in one room, interpretation in another—applied to obligation: commitments in one room, commentary in another.)

🔄 Check Your Understanding A reviewer reads this line in a spec: "Note: the system should be designed to scale horizontally." Two things are wrong with it from an RFC 2119 standpoint. What are they?

Answer

First, it mixes normative and informative. It's labeled "Note:" (informative—explanation, not a requirement), but it contains "should" (a normative keyword signaling a recommendation). Is this a requirement or a comment? The reader can't tell, which is exactly the confusion the normative/informative split exists to prevent. Second, even read as normative, "scale horizontally" is not testable—it names an architectural style, not a verifiable behavior. What test returns pass/fail on "designed to scale horizontally"? Fix: decide what you actually mean. If it's a real requirement, make it testable and normative ("REQ-SCL-001. The system SHALL sustain a 10× increase in load by adding stateless application instances, with no change to the application code"). If it's genuinely just design guidance, drop the "should," keep it clearly informative ("Note: the architecture anticipates horizontal scaling; see the design doc, §4"), and put the real, testable scaling requirement elsewhere.

33.4 The Requirements Specification: Organizing for Build and Verification

Individual requirements live inside a requirements specification—the organized document that a team builds from and verifies against. Its structure serves two readers at once: the engineer who needs to find the requirements for the part they're building, and the verifier who needs to confirm every requirement is met. Structure-serves-the-reader (Chapter 4, theme 5) governs here as much as anywhere, but the "reader" includes a tester checking off a list, so the structure has to support traceability—the ability to follow each requirement from its origin to its verification.

A typical requirements spec is organized roughly like this (the exact template varies by field and by which standard a team follows, but the bones are stable):

• Front matter: title, document ID, version, revision history, approvals. (Engineering docs are controlled—who approved which version matters, especially under audit. This is Chapter 22's SOP revision record, raised to a discipline.)
• Introduction / scope: what system this specifies, what's in scope and explicitly out of scope. Out-of-scope statements prevent the "I assumed it would also do X" disputes.
• Definitions and references: terms of art, acronyms, and the external standards this spec invokes (e.g., "all uppercase keywords are to be interpreted per RFC 2119").
• Functional requirements: what the system does (the behaviors). Grouped by feature or subsystem.
• Non-functional requirements: the qualities the system must have—performance, security, reliability, usability, maintainability, regulatory. (The famous "-ilities.") These are the ones most often written as wishes, so they need the most discipline.
• Constraints and interfaces: the environment, the standards it must comply with, the systems it must talk to and the exact formats of those exchanges.

The single most important structural habit is the requirement ID and traceability. Every requirement gets a unique, stable identifier (REQ-PERF-001, SR-4.2.3, whatever your scheme)—not a bullet that renumbers when someone inserts a line. The ID is the thread that lets you trace a requirement forward (which design element implements it, which test case verifies it) and backward (what stakeholder need or higher-level requirement it came from). When a requirement has no parent need, it might be gold-plating—a feature nobody asked for. When a requirement has no test case, it's unverified—you don't know if it's met. The discipline is captured in a traceability matrix: a table mapping each requirement to its source, its design element, and its verification.

Figure 33.1 (described): a requirements traceability matrix. A table with one row per requirement. Columns, left to right: Requirement ID (REQ-PERF-001), Requirement text (abbreviated), Source (the stakeholder need or parent requirement it traces back to, e.g., "Customer SLA §2"), Design element (the module or component that implements it, e.g., "SearchService"), Verification method (Test / Inspection / Demonstration / Analysis), and Test case ID (TC-PERF-001). A reader scanning the matrix can instantly spot two failure modes: a row with an empty Source cell (a requirement nobody asked for—possible gold-plating) and a row with an empty Test case cell (a requirement nobody is verifying—an unproven claim). The matrix turns "is everything traceable?" from a vague worry into a column you can scan for blanks.

✏️ Try This Take any feature you understand well (a password reset, a thermostat's scheduling, an e-commerce checkout). Write three requirements for it—one functional, one performance (non-functional), one error-handling—each with an ID, each atomic, each testable, each using a correct RFC 2119 keyword. Then, for each, write the one-line verification method (Test/Inspection/Demonstration/Analysis and what you'd actually do). If you can't write the verification line, the requirement isn't done yet.

A note on the difference between a requirement and a design. A requirement says what the system must do or achieve; the design says how it will do it. "The system shall return search results within 500 ms" is a requirement (it states the what, the outcome to verify). "The system will use an in-memory index with a Redis cache" is a design choice (it states the how). The discipline is to keep requirements free of design wherever you can, because every design detail you bake into a requirement is a decision you've taken away from the engineers—and sometimes a constraint you didn't mean to impose. Specify the speed; let the designers choose the cache. (There are exceptions—sometimes a specific interface or standard is genuinely required—but the default is specify the what, leave the how to design.) This is the same separation Chapter 13 draws between Results and Discussion, and Chapter 4 draws between the conclusion and the supporting detail: keep the levels distinct so the reader knows which one they're reading.

33.5 Design Documents: Writing the How and the Why

If the requirements spec says what the system must do, the design document says how it will do it—and, just as importantly, why it was designed that way. This is the document an engineer writes to think through a design before building it, to get it reviewed, and to leave a record that the next engineer can understand. (In software it's often called a "design doc" or "technical design"; the close cousin focused on a single decision is the Architecture Decision Record, covered in Chapter 34. In hardware and systems work it may be a design description or a design report.)

A design document's reader is a peer engineer—someone with the technical background but without your head full of context. The job is to transfer the design and the reasoning into their head efficiently enough that they can evaluate it, build on it, or maintain it years later. That last reader—the future maintainer who inherits a system and asks "why on earth did they do it this way?"—is the one design docs most often fail. The reasoning that was obvious to you while you were deciding is invisible six months later, to you most of all. The most valuable sentences in a design document are the ones that record why you rejected the alternative.

A workable design-document structure (adapt to your field):

• Context / problem: what problem this design solves, and the requirements it must satisfy (link them by ID—traceability again).
• Goals and non-goals: what this design is and isn't trying to achieve. Non-goals prevent scope creep and "why didn't it also do X?" reviews.
• Proposed design: the architecture, the components, the data flow, the interfaces. Use diagrams (Chapter 32)—a system is often clearer as a labeled diagram than as three paragraphs of prose.
• Alternatives considered: the other designs you weighed and why you rejected them. This is the section reviewers read most carefully and authors most often skip. It's the difference between "trust me" and "here's my reasoning, check it."
• Trade-offs and risks: what this design costs, where it's weak, what could go wrong, how you'll mitigate it.
• Verification / rollout: how you'll test it and deploy it safely.

❌ Before (a design doc that records only the decision): We will use a message queue between the order service and the fulfillment service.

✅ After (records the reasoning and the alternatives): We will decouple the order service and the fulfillment service with a message queue (proposed: a managed queue service).

Why: order spikes during sales events exceed fulfillment's processing rate by up to 5×. A synchronous call would force the order service to either block (degrading checkout latency, violating REQ-PERF-001) or drop orders under load. A queue absorbs the spike and lets fulfillment drain it at a sustainable rate.

Alternatives considered: (1) Synchronous HTTP with retries — rejected: doesn't solve the rate mismatch, and retries amplify load during exactly the spike we're trying to survive. (2) A shared database table as a work queue — rejected: couples the two services' schemas and creates lock contention at high write rates. (3) The managed queue — chosen: absorbs spikes, decouples the services, and the operational cost is acceptable given our existing use of the same provider.

Why it's better: The "before" tells a future reader what was done but nothing about why, so when the queue causes some new problem in two years, the maintainer has no idea whether it's safe to remove it—they don't know what it was solving. The "after" records the forcing constraint (the 5× rate mismatch), ties it to a requirement by ID, and—most valuably—documents the two rejected alternatives with the reason for rejection, so the next engineer doesn't waste a week re-evaluating the synchronous approach that was already considered and rejected for a specific reason. The design doc became a record of thinking, not just a record of a decision. (This is theme 1, writing-is-thinking, in its engineering form: writing the "alternatives considered" section is how you discover whether you actually considered them.)

A design document is also where the prose-versus-diagram judgment from Chapter 9 and Chapter 32 earns its keep. A data flow, a state machine, a sequence of calls between services—these are almost always clearer as a diagram than as prose, and the best design docs lean on diagrams for structure and use prose for the reasoning a diagram can't carry (the why, the trade-offs, the rejected paths). Don't narrate in paragraphs what a labeled box-and-arrow diagram shows at a glance; don't try to encode a subtle trade-off in a diagram when a sentence states it precisely.

33.6 Test Plans and Test Reports: Proving the Requirements Are Met

If a requirement is a commitment that will be verified, the test plan is the document that says how it will be verified, and the test report is the document that says whether it was. Together they close the loop the requirements spec opened: every "shall" in the spec should have a test that decides it, and every test should trace back to the requirement it verifies. This is traceability completing its circuit.

A test plan describes what will be tested and how. Its core unit is the test case, and a good test case has the same DNA as a good requirement (because it's verifying one) plus the structure of a good procedure (Chapter 22, because someone has to execute it):

• Test case ID and the requirement ID(s) it verifies (traceability—a test that verifies no requirement is testing something nobody asked for).
• Preconditions / setup: the state the system must be in before the test (Chapter 22's "Before you begin").
• Steps: the actions, one per step, in order, in the imperative (Chapter 22 again—a test case is a procedure).
• Expected result: the specific, observable outcome that constitutes a pass. This is the heart of the test case, and the place test plans most often go vague.
• Pass/fail criterion: unambiguous, so any tester reaches the same verdict.

The defining failure of a weak test case is the vague expected result—the same disease as the vague requirement, now in the verification.

❌ Before (a test case with a vague expected result): Test that search works correctly under load. Expected: search performs well and returns good results.

✅ After (a testable test case): TC-PERF-001 — verifies REQ-PERF-001 Precondition: Test environment seeded with the 1M-record reference dataset; load generator configured for 1,000 concurrent users issuing the standard query mix. Steps: 1. Start the load generator at 1,000 concurrent users. 2. Sustain the load for 10 minutes. 3. Record the response-time distribution measured at the API boundary.

Expected result: The 95th-percentile response time is ≤ 500 ms for the full 10-minute window. Fewer than 0.1% of requests return a 5xx status. Pass/fail: Pass if both conditions hold for the full window; fail if either is violated at any point after the first 30 seconds (warm-up excluded).

Why it's better: "Performs well and returns good results" gave the tester nothing to decide on—two testers would reach two verdicts, which means the test verifies nothing. The "after" names the exact thresholds (≤ 500 ms at p95, < 0.1% 5xx), the precise conditions (1M records, 1,000 users, 10 minutes), and an unambiguous pass/fail rule (including the honest detail of excluding warm-up). It also traces explicitly to REQ-PERF-001, closing the loop. Notice that the expected result is the requirement, restated as a measurement—which is only possible because the requirement was testable in the first place. A vague requirement makes a testable test case impossible; the precision you invested in §33.2 pays off here.

The test report records what happened when the plan was run: for each test case, the result (pass/fail), the actual measured values (not just "pass"—the numbers, so a reader can see the margin), the environment and build version tested, and any deviations or anomalies. A test report follows the same honesty discipline as a Results section in Chapter 13: report what you observed, neutrally, including the failures and the surprises. A test report that hides a marginal pass ("p95 was 498 ms—technically a pass") or omits the flaky test is the engineering equivalent of editorializing in Results, and it's worse, because someone will make a ship/no-ship decision on it. Record the actual number. Let the margin be visible. If a test was skipped or a result was anomalous, say so plainly; the reader needs to know what wasn't proven as much as what was.

🔄 Check Your Understanding Why should a test report record the actual measured value (e.g., "p95 = 498 ms") rather than just the verdict ("PASS")?

Answer

Because the verdict alone hides the margin, and the margin is decision-relevant information. "PASS" against a 500 ms requirement could mean the system measured 50 ms (huge headroom, robust) or 498 ms (two milliseconds from failure, fragile, likely to fail under any small regression or on a slightly busier day). A reader making a ship decision, or an engineer deciding whether a risky optimization is worth it, needs to know which. Recording the number is the same discipline as Chapter 13's Results section—report the observation, not just your conclusion about it—so the reader can judge the evidence rather than trusting your summary of it. A bare "PASS" is the test-report version of editorializing: it tells the reader your verdict but withholds the data they'd need to form their own.

33.7 Safety and Compliance Documentation: Writing for the Auditor

Some engineering documents exist because a regulation, a standard, or a safety case requires them. Compliance documentation demonstrates that a product meets an external standard; safety documentation demonstrates that hazards have been identified and controlled. The reader here is new: an auditor, a regulator, a certification body, or—in the worst case—an investigator after something went wrong. They are reading adversarially in the precise sense of §33.1: looking for the gap between what the standard requires and what you actually did.

This reader changes how you write in three specific ways:

Trace everything to the requirement it satisfies. A compliance document's job is to map, claim by claim, from the standard's requirements to your evidence that you meet them. "We follow the standard" is worth nothing to an auditor; "Clause 7.3 of the standard requires X; we satisfy it via design element Y, verified by test TC-Z, evidence in Appendix C" is worth everything. This is the traceability matrix again, now pointing outward at an external standard instead of inward at stakeholder needs. Auditors live in these maps.

Write what you'll actually do, not what sounds good. A safety procedure or compliance claim is a commitment you can be audited against and held to. If you write "all units are inspected before shipment" and an auditor finds an uninspected unit, the gap between your document and your practice is itself a finding—sometimes a worse one than the original defect, because it shows your documentation can't be trusted. Document the process you genuinely follow, not an idealized one. (This is Chapter 22's SOP discipline with legal teeth: the document and the practice must match.)

Hazards: name the hazard, the cause, the effect, and the control. Safety documentation centers on a hazard analysis, and a well-written hazard entry has a fixed anatomy that mirrors Chapter 22's rule for warnings (name the hazard, the why, and what to do):

❌ Before (a vague hazard entry): The battery could be dangerous if it overheats. Be careful with thermal management.

✅ After (a structured hazard entry): - Hazard: Thermal runaway of the lithium-ion cell. - Cause: Charging above 45 °C, or a charge current exceeding the cell's rated maximum. - Effect: Cell venting, fire; risk of injury and equipment loss. - Severity / likelihood: Catastrophic / Remote (per the project's risk matrix). - Control: The charging circuit SHALL disable charging when the cell temperature exceeds 45 °C (verified by TC-SAFE-004) and SHALL limit charge current to the rated maximum in firmware (verified by TC-SAFE-005). - Residual risk: Low, with both controls active.

Why it's better: "Be careful with thermal management" is useless to everyone—it names no specific hazard, no cause, no control, and nothing testable. The structured entry identifies the exact hazard (thermal runaway), the exact causes (over-temperature charging, over-current), the consequence, and—critically—the specific, verifiable controls written as SHALL requirements that trace to test cases. An auditor can confirm the control exists and was tested. A safety case is only as good as the traceability from each identified hazard to a verified control; "be careful" traces to nothing.

A word on tone and honesty in safety documentation, because it's the place where the ethics of clarity (Chapter 38) bite hardest. The temptation under schedule pressure is to soften a risk, to write "unlikely" where the data says "possible," to bury a known limitation in an appendix. Resist it completely. Safety documentation is where the buried-conclusion failure of the Challenger memos (Chapter 4, Chapter 38) becomes lethal: a real risk, known to the engineers, that failed to reach the decision-makers with the clarity and prominence the danger warranted. Write the risk plainly, put it where it will be seen, and state your uncertainty honestly. Calibrate your language to the evidence exactly as Chapter 13 taught—"suggests," "is consistent with," "has not been tested above 60 °C"—because here the reader may bet a life on your words.

33.8 The Engineering Notebook: Writing as You Work

Not all engineering writing is for someone else. The engineering notebook (or lab notebook, or design journal) is the running, dated record an engineer keeps of what they did, what they observed, what they decided, and why. It is part memory aid, part legal record, and part thinking tool—and in some settings (notably anything touching patents) it is a formal document with rules about how it's kept.

The notebook serves several readers, most of them future:

• Future you, three weeks from now, who has forgotten exactly which parameter you changed and what happened.
• A colleague picking up your work, who needs to reconstruct your reasoning.
• A patent attorney or court, who may need to establish when you conceived or reduced an idea to practice. (This is why traditional engineering notebooks are bound, page-numbered, written in ink, dated, and sometimes witnessed—so the record can't be quietly altered after the fact. The legal weight is real even where the bound-paper ritual has moved to controlled electronic systems.)

Good notebook writing has a different discipline from the polished documents above. It is contemporaneous—written as you work, not reconstructed later—because its value as memory and as evidence depends on it being a true record of the moment. It records the failures and dead ends, not just the successes, because a dead end you don't record is one you'll waste time re-exploring (and because "what didn't work" is often the most useful thing for the next person). And it captures the why of decisions while the reasoning is still fresh, since the reasoning is exactly what evaporates fastest.

❌ Before (a notebook entry written to look tidy): Tuned the controller. Works now.

✅ After (a contemporaneous, useful entry): 2026-06-04. PID controller for the temperature loop was overshooting setpoint by ~8 °C and oscillating (period ~12 s). Reduced Kp from 4.0 → 2.5 and added Kd = 0.8. Overshoot dropped to ~1.5 °C, oscillation gone, settling time ~20 s (acceptable per REQ-CTL-003). Did NOT change Ki (integral) — suspected windup but ran out of time to confirm; revisit. Test data in run-log 2026-06-04-a.csv.

Why it's better: "Tuned the controller. Works now." is worthless to future-you and to the patent record alike—it has no date, no values, no observations, no reasoning, and no honesty about what's still uncertain. The contemporaneous entry records the symptom (8 °C overshoot, 12 s oscillation), the exact change (Kp 4.0→2.5, Kd 0.8), the measured result, an explicit open question (the untested integral-windup suspicion), the link to a requirement, and a pointer to the data. Three weeks later, future-you can pick up exactly where you left off—including the loose thread you flagged. The notebook entry is doing the same job as a design doc's "alternatives considered," at the granularity of a single afternoon.

The notebook is theme 1 (writing-is-thinking) in its rawest form. You don't keep a notebook to have a record—or not only. You keep it because writing down what you just observed and what you'll try next is how you reason through a hard problem without losing the thread. The act of writing "did NOT change Ki — suspected windup but didn't confirm" is what keeps the open question alive in your mind. Engineers who keep good notebooks aren't more diligent; they're externalizing their working memory so they can think about harder problems than their head holds at once.

🪞 Learning Check-In Think about how you currently keep track of your own technical work—debugging sessions, experiments, design decisions, things you tried that didn't work. Do you write it down as you go, or reconstruct it later (or not at all)? Be honest about the cost: how many times have you re-debugged something you'd already solved, or changed a setting back to a value you'd already rejected, because you didn't record why you rejected it? The notebook habit is one of the highest-return writing habits in engineering, and almost nobody is taught it. What would it take for you to keep a real, dated, honest record of your next project—including the dead ends?

33.9 Writing for Manufacturing: Work Instructions and Assembly Procedures

At the far end of the engineering pipeline, a design becomes a physical thing someone builds—on an assembly line, at a workbench, in a clean room. The documents that govern that step are work instructions and assembly procedures, and they are Chapter 22's procedural writing pushed to its most demanding application. The reader is an operator performing the task, often repeatedly, often under time pressure, sometimes in a different language from the author, sometimes with the document laminated on a stand beside the work. Everything from Chapter 22 applies—one action per step, imperative mood, warnings before the step, the "someone who has never done this" test—and the manufacturing context adds its own intensifications.

Precision is per-unit and cumulative. A work instruction that's ambiguous doesn't fail once; it fails on every unit, thousands of times, until someone notices the defect rate. A single under-specified torque value ("tighten the bolt firmly") becomes a population of over- and under-torqued joints. So manufacturing instructions specify the exact value and tolerance for everything that matters: "Torque the four M6 bolts to 9 N·m ± 0.5 N·m in the cross-pattern shown in Figure 4, in the sequence 1-3-2-4." Not "tighten the bolts"—the value, the tolerance, the pattern, the sequence.

Visuals often carry the instruction. On a line, an annotated photo or diagram of the exact part in the exact orientation frequently communicates faster and more reliably than prose, and crosses language barriers (Chapter 22's annotated-screenshot discipline, on the factory floor). But the same caution applies: the text instruction stays authoritative (name the part, the value), and the visual must match the current revision of the part—a work instruction showing a superseded component actively causes defects.

Quality checks are built into the steps. Manufacturing procedures interleave verification with action: do the step, then confirm it before moving on ("After seating the connector, confirm the latch clicks and the locking tab is flush—if it is not flush, the connector is not seated; remove and reseat"). This is the in-line quality gate, and it's the manufacturing version of Chapter 22's "tell the reader how to know it worked." A defect caught at the station that caused it is cheap; the same defect caught at final test, or by a customer, is expensive—the same cost gradient from §33.1, now inside the assembly sequence.

❌ Before (a work instruction written like prose): Attach the heat sink to the processor using the thermal paste, being careful to apply the right amount and to secure it properly so it makes good contact.

✅ After (a manufacturing work instruction): Step 7 — Install heat sink (see Figure 7; required: thermal paste TIM-2, torque driver set to 0.4 N·m)

⚠️ Caution: Too much thermal paste degrades heat transfer and can short adjacent pins. Apply only the specified amount. 1. Apply one 5 mm bead (≈ 0.1 mL) of TIM-2 to the center of the processor lid. 2. Lower the heat sink straight down onto the processor (do not slide—sliding spreads paste onto adjacent components). 3. Tighten the four captive screws to 0.4 N·m in the diagonal sequence 1-3-2-4 (Figure 7). 4. Verify: the heat sink does not rock when gently nudged. If it rocks, a screw is under-torqued—re-torque per step 3.

Why it's better: "The right amount" of paste became "one 5 mm bead (≈ 0.1 mL)"—a value an operator can reproduce identically on every unit. "Secure it properly" became an exact torque (0.4 N·m), an exact pattern (1-3-2-4), and a verification step (the rock test). The hazard (too much paste) moved to a caution before the step it governs. The reference figure is named. An operator who has never built this unit—and the next operator, and the one after a shift change—can now produce the same result the same way every time, which is the entire point of a work instruction: not to describe the assembly, but to make it repeatable across people and across thousands of units. (This is Chapter 22's SOP reproducibility test—"would two people do this identically?"—scaled to a production line.)

33.10 Common Mistakes & Practical Considerations

The errors below recur across requirements, specs, design docs, test plans, and work instructions. Almost all of them trace to the same root the chapter opened with: writing a sentence that feels like a specification but isn't testable.

"The system should be fast" — the untestable requirement. The flagship error. Any quality word with no number, no condition, and no verification method: fast, robust, scalable, intuitive, secure, reliable, efficient. The cure is mechanical: for every requirement, write the test that decides it. If you can't, the requirement isn't done.

The compound requirement. "And" hiding two (or five) requirements in one statement, so it can't be tracked or marked pass/fail as a unit. Split at every "and" that joins independent obligations.

Modal mush. "Will," "should," "needs to," "is supposed to," "ideally would," all mixed together so the reader can't tell what's mandatory. Adopt RFC 2119 keywords, use them in their defined sense, and say so in your definitions section.

Mandatory-everything (the all-SHALL spec). The over-correction: making every requirement a SHALL so nothing can be traded off. It signals you haven't decided what actually matters, and it ties the implementer's hands on requirements that should have been SHOULDs. Reserve SHALL for the genuinely non-negotiable.

Design baked into requirements. A requirement that mandates a specific implementation ("the system shall use a Redis cache") when it should mandate the outcome ("the system shall return results within 500 ms"). You've taken a decision away from the designers and possibly over-constrained the solution. Specify the what; leave the how to design unless the how is genuinely required.

Normative/informative blur. Explanation that reads like a requirement, or a "Note:" that contains a "shall." Keep commitments and commentary visibly separate, so a reader knows instantly whether a sentence binds them.

The orphaned requirement. A requirement with no source (nobody asked for it—possible gold-plating) or no test case (nobody is verifying it—an unproven claim). The traceability matrix exists to make these blanks visible; scan for them.

The tidy-but-false record. A test report that rounds a marginal pass into "PASS" without the number, a notebook reconstructed after the fact, a compliance doc describing an idealized process you don't actually follow. In engineering, a document that doesn't match reality is worse than no document—it's a trap for the next reader and, under audit, a finding in itself.

The "it depends" — how much rigor? Not every document needs a full traceability matrix and four verification methods per line. A two-week internal tool and a flight-control system are both built from requirements, but the rigor scales with the cost of being wrong. The calibrating question is the same one Chapter 22 asked about granularity: what happens if this is wrong? High-stakes, regulated, safety-critical, or long-lived systems justify the full discipline; a throwaway prototype does not. The skill is matching the rigor to the stakes—neither shipping a safety-critical spec full of "shoulds be fast," nor burying a one-off script under a defense-grade requirements process. Read your context, as you read your audience.

📚 Going Deeper: Standards about how to write requirements There is a whole layer of engineering standards that govern not the product but the documents—how to write requirements, how to structure a software requirements specification, how to do systems and requirements engineering. The IEEE and the joint ISO/IEC/IEEE bodies publish recommended practices for software and systems requirements specifications and for the requirements-engineering process; aerospace, automotive, and medical-device sectors layer their own (e.g., the documentation expectations that accompany safety standards in those fields). You do not need to memorize standard numbers—and you should never invent one. What you need to know is that (1) these standards exist, (2) your employer or your contract likely names the specific ones you must follow, and (3) they largely codify the same disciplines this chapter teaches: atomic, unambiguous, testable, traceable requirements with defined obligation levels. When you join a team, find out which standards govern your documents and read them; the principles will already be familiar. See further-reading.md for the verifiable starting points (RFC 2119 chief among them).

📐 Project Checkpoint

Portfolio Piece 1 (Technical Report) → adding an engineering requirements section.

Your portfolio's technical report (Piece 1, begun in Part III) documents a system, an investigation, or a project. This chapter gives you the chance to add the most field-specific, high-signal artifact an engineering reader looks for: a small, well-formed requirements section.

Recall the prior increment. Through Part III you learned to document what you did and found (Chapter 13's IMRaD; the recommendation-first technical report). That writing looks backward—it records results. Engineering requirements look forward—they specify what a system must do before it's built. Adding a requirements section shows you can write in both directions.

This chapter's addition — write a requirements set. For the system your report concerns (or a system you know well), draft 6–10 requirements that meet this chapter's standard: - Each has a unique ID and is atomic (one requirement per statement). - Each uses a correct RFC 2119 keyword (SHALL/SHOULD/MAY) in its defined sense—include at least one of each to show you understand the distinction. - Each is testable: it names a measurable value, the condition, and (in a trailing note or a small matrix) its verification method (Test/Inspection/Demonstration/Analysis). - Cover both functional (what it does) and non-functional (performance, reliability, security) requirements. - Add a tiny traceability matrix (even 6 rows): requirement ID → source → verification method → test case ID. Scan it for blanks.

Then run the chapter's audit on your own draft: hunt every weak word ("fast," "robust," "user-friendly"), split every compound requirement, and confirm each one has a test you could actually run. The single best self-check is the threshold question on every line: could someone build this, and could someone else prove whether they did?

Preview the next increment. In Chapter 34 (Writing for Computer Science) the same precision turns toward the software-team genres—design docs, ADRs, pull-request descriptions, bug reports, blameless postmortems—where a requirement's clarity becomes a code review's kindness and a bug report's reproducibility. The "testable" discipline you built here is the same discipline that makes a bug report actionable: expected vs. actual, stated precisely enough to verify.

Frequently Asked Questions

What does SHALL mean in a specification, and how is it different from SHOULD and MAY?

In requirements writing, the modal verb states the strength of the obligation, and the most common standard for these words is RFC 2119. SHALL (and MUST) means an absolute requirement—mandatory; failing to do it means the system does not conform. SHOULD means a recommendation—do it unless you have a carefully considered, documented reason not to. MAY means truly optional—doing it or not are both conformant. The convention is to write the keywords in uppercase when you mean the defined sense, and to state in your document that the keywords follow RFC 2119. Choose SHALL only for what is genuinely non-negotiable; a spec where everything is SHALL has prioritized nothing.

How do I rewrite a vague requirement like "the system should be fast" as a testable requirement?

Add the three things "fast" is missing: a measurable value, the condition under which it's measured, and a verification method. "The system should be fast" becomes, for example, "REQ-PERF-001. The system SHALL return search results within 500 ms at the 95th percentile, measured at the API boundary, under a sustained load of 1,000 concurrent users." Now there's exactly one reading and a test that returns pass or fail. The self-check is the threshold question: what test decides this? If you can't name the test, the requirement isn't finished—it's still a wish.

What makes a requirement "testable," and why does it matter so much?

A requirement is testable (verifiable) if there exists a method—Test, Inspection, Demonstration, or Analysis—that returns an unambiguous pass or fail. It matters because a requirement is a commitment that will be verified: if no test can decide it, it commits no one to anything and can be neither met nor violated. Untestable requirements ("robust," "user-friendly," "modern") are the single most common and most expensive defect in specifications, because the disagreement they hide doesn't surface until the wrong thing has been built. Write the test in your head as you write the requirement.

What's the difference between a requirements document and a design document?

A requirements document says what the system must do or achieve—the outcomes to be verified (e.g., "shall return results within 500 ms"). A design document says how it will do it and why that approach was chosen (e.g., "uses an in-memory index with a cache, because…"). Keep them separate: requirements free of design leave the implementation decisions to the engineers, and a design doc's most valuable content is the reasoning—especially the "alternatives considered" and why you rejected them, which is what a future maintainer most needs and authors most often omit.

How is engineering writing different from other technical writing?

Two ways. First, the document comes before the thing: you write the requirement and then build to it, so a vague sentence gets the wrong thing built rather than merely confusing a reader—and the cost of fixing the error rises sharply at each stage it survives. Second, engineering documents are read adversarially: by testers hunting for unmet "shalls," auditors checking compliance, and sometimes investigators after a failure. So the field has standardized a discipline of precision—atomic, testable, traceable requirements with defined obligation keywords—that exists specifically so two competent people can't read the same spec two ways.

Chapter Summary

Key Takeaways

• A requirement that cannot be tested is not a requirement—it is a wish. For every requirement, ask "what test returns pass or fail?" If you can't name one, it isn't finished.
• Good requirements are atomic, unambiguous, and testable. One requirement per statement (split at "and"); exactly one reading (hunt the weak words—fast, robust, user-friendly); a named verification method (Test/Inspection/Demonstration/Analysis).
• The modal verb carries the obligation (RFC 2119). SHALL/MUST = mandatory; SHOULD = recommended with a deliberate escape hatch; MAY = optional. Choosing the keyword forces you to decide how strong each obligation really is.
• Keep normative and informative text separate, and keep requirements (the what) free of design (the how)—specify the outcome, leave the implementation to the designers.
• Traceability is the spine of a spec. Every requirement gets a stable ID and traces to its source and its test. A requirement with no source may be gold-plating; one with no test is unverified.
• Design docs record the why (especially rejected alternatives); test reports record the number (not just "PASS"); safety docs trace each hazard to a verified control; the notebook is contemporaneous and honest about dead ends; work instructions make the build repeatable across people and units.

Action Items

• Take one vague requirement you've seen ("fast," "robust," "scalable") and rewrite it as a testable SHALL statement with a value, a condition, and a verification method.
• Audit a spec (yours or a sample) for weak words, compound requirements, and modal mush; fix each.
• Add requirement IDs and a small traceability matrix; scan for blank source or test columns.
• In your next design doc, write the "alternatives considered" section with the reason you rejected each.
• Start a dated, contemporaneous notebook for your next project—record the dead ends, not just the wins.

Common Mistakes

• Untestable requirements ("the system should be fast"); compound requirements ("and"); modal mush ("will/should/ideally"); all-SHALL specs; design baked into requirements; normative/informative blur; orphaned requirements (no source or no test); tidy-but-false records (a rounded "PASS," an idealized compliance doc).

Decision Framework

Spaced Review

A few questions reaching back, to strengthen retention.

1. (From Chapter 22) Chapter 22's diagnostic was the "someone who has never done this" test—watch a beginner try your instructions and treat every stall as a defect. A test case in a test plan (§33.6) is itself a procedure someone executes. How is "the expected result must be unambiguous enough that any two testers reach the same verdict" the same idea as Chapter 22's test, and what's the engineering twist?
2. (From Chapter 4) Chapter 4 taught BLUF and that "being correct is not the job; being received is" (the Challenger lesson). Where in this chapter does that same lesson reappear with the highest stakes, and what's the writing move that prevents the failure?
3. (From Chapter 13, bridging) Chapter 13 drew a hard line between Results (what happened, stated so neutrally a rival would accept it) and Discussion (what it means). Name two places in this chapter where that exact separation reappears under different names.

What's Next

Chapter 34 (Writing for Computer Science: From Code Reviews to Architecture Decision Records) keeps you in the engineering world but turns toward the documents a software team lives in day to day. The requirements precision you built here becomes the backbone of several of them: a design doc and an Architecture Decision Record (the "alternatives considered" section, formalized), a pull-request description (what, why, how to test), a bug report a developer can actually act on (expected vs. actual—testability again), user stories with acceptance criteria (requirements in another costume), and the blameless postmortem. The throughline is the same one this chapter turned on: write so the next person can build, verify, or fix the thing—precisely, and without having to guess what you meant.

Practice: Exercises · Quiz Go deeper: Case Study · Case Study 2 Review: Key Takeaways · Further Reading