“Write it in more detail” is an instruction with no pass mark. The person writing never knows when to stop, and the person asking only says it is not enough after the writing is done.
Three organisations wrote a pass mark down. NASA put one in an appendix, a group of Rolls-Royce engineers built one into a sentence template, and a Korean government guide turned one into a counting rule. None of them was written with the others in mind, and they check different things. Run a sentence past all three and you find out fast whether it is worth keeping.
Sort out the names first
Too many words point at the same thing. An RFP is the whole procurement document, including scope, schedule and scoring. The requirements document is the list of requirements that sits inside it or beside it. Textbooks call that list an SRS, a software requirements specification. Some teams call it a technical requirements document and mean the same file.
A PRD is a slightly different animal, and I sorted that difference out in the piece on meeting terms. Whatever the file is called, what goes in it is sentences. So this piece is about sentences, not about the template. A blank template does nothing for you if you do not know what belongs in the cells.
Test one: can anyone check it later?
A requirement has to produce a pass or a fail when the work is delivered. NASA attached a guide to writing good requirements to its systems engineering handbook, and the most useful part of it is a list of words you are told not to use.
Flexible. Easy. Sufficient. Safe. Adequate. User-friendly. Usable. Appropriate. Fast. Robust. Quickly. Easily. Clearly. The handbook throws in “as appropriate”, “etc.”, “and/or” and “but not limited to” for good measure, and adds a general warning about words ending in “ly” and “ize”.
What these have in common is that they cannot settle an argument. Put “the page shall load quickly” in a document and at handover the builder says it does and the buyer says it does not, and both of them point at the same line. The document was written so that it cannot decide, so whoever is more insistent decides instead.
The same appendix separates three verbs that English speakers use interchangeably. Shall is a requirement. Will states a fact or a declaration of purpose. Should is a goal. Mixing them inside one table means that at review time nobody can tell which lines were promises.
One more rule from the same page: a requirement should be free of implementation. Write what has to be true, not how to build it. Once the how is written into the contract, a better how discovered in month three is a change request instead of an improvement.
Test two: is the condition at the front of the sentence?
The second test is about shape. EARS came out of Rolls-Royce, where Alistair Mavin and colleagues were working through the airworthiness regulations for a jet engine control system, and it was first published in 2009. It says a requirement is one of five kinds, and gives each kind a keyword that goes at the start.
| Kind | Template | Example |
|---|---|---|
| Always true | The system shall … | The mobile phone shall have a mass of less than 150 grams. |
| While in a state | While …, the system shall … | While there is no card in the ATM, the ATM shall display “insert card to begin”. |
| When something happens | When …, the system shall … | When “mute” is selected, the laptop shall suppress all audio output. |
| Only if a feature exists | Where …, the system shall … | Where the car has a sunroof, the car shall have a sunroof control panel on the driver door. |
| When something goes wrong | If …, then the system shall … | If an invalid credit card number is entered, then the website shall display “please re-enter credit card details”. |
The templates are not the clever part. Laying the five kinds side by side is. Most requirements documents contain rows one and three and nothing else, which means nobody has written down what happens when things fail. That gap shows up late, as the sentence “we never discussed that case”.
Putting the condition at the front rather than the end matters too. Trailing conditions get read after the reader has already pictured the feature, and by then the picture is set.
Test three: is the reason written down?
The third test is the one people skip. NASA asks that each requirement come with an intelligible rationale, including any assumptions it rests on. Not the requirement itself. The reason it exists.
This sounds like paperwork until a requirement has to change. Six months in, someone asks whether the response time can go from two seconds to four. If the line says only “the search results shall appear within two seconds”, the answer is a meeting. If it also says the two seconds came from a call centre script where the operator reads the result aloud to a caller on hold, the answer takes ten seconds, and it is no.
The same appendix handles unfinished requirements in the same spirit. Where a value is not known yet, it prefers TBR, to be resolved, over TBD, and asks for the rationale behind the gap. The point is not that gaps are forbidden. It is that a gap needs a name and an owner, because an unnamed gap is nobody’s job.
Korean public procurement arrives at the same place from another direction. The official requirements table used in government software tenders has seven columns, and the last one is the source of the requirement: who asked for it and why. It is the same instinct as NASA’s rationale, turned into a cell that cannot be left empty.
Running the three tests on a real sentence
While reworking the image tool for this blog I wrote myself a requirement: the card generator has to accept a size argument, and cards produced at the old 1200×630 size have to come out pixel-identical to the existing files.
Run the tests. Can anyone check it later? Compare the old file and the new file byte by byte. Is the condition at the front? Yes, at the 1200×630 size. Is the reason written down? Yes, twenty-odd published articles already point at those images and a regenerated card would change them all.
I regenerated the old cards afterwards and the difference was zero. The number is not the interesting part. The interesting part is that I could establish it without asking anyone’s opinion. Had I written “make sure the existing cards don’t break”, there would have been no way to close the question.
The same job produced the opposite case. A shared banner image was agreed on, but where the file should live was not, and that hole sat inside the requirement without anyone naming it. It only got closed because someone eventually asked the question out loud, which is exactly what TBR exists to prevent.
The categories people forget
First drafts describe screens and features and stop. NASA’s validation checklist is a decent way to catch what fell out, because it walks a set of headings that have nothing to do with each other: clarity, completeness, consistency, traceability, correctness, functionality, performance, interfaces, maintainability, reliability, verifiability, data usage.
Read down that list once your draft is finished and look for headings with no line under them. Maintainability and verifiability are usually the empty ones, and those two being empty is how acceptance criteria and handover end up being negotiated after delivery rather than before it.
Where to start
If a document already exists, do not rewrite it. Do two passes. First, find the lines that use a word from the banned list and replace each one with a number or a method of checking. Second, count the lines that describe what happens when something fails. If that count is zero, that is the largest hole you have, and it is larger than anything in the feature list.
If you are starting fresh, open the template last. Write sentences first, run each one past the three tests, and copy across only the ones that pass. Opening the template first turns filling cells into the goal, and a cell will accept anything.
To be straight about it: I have never run a procurement or bid on one. The tests above come from reading published guides and standards documents, and the example requirements come from work notes I wrote for myself while running this blog, not from a contract. The scale is nowhere near the same. Whether a sentence could be checked or not split exactly the same way. If the order of the whole project is the more pressing question, the piece on development phases comes first.