翻訳待ち：What good requirements look like (and how to write them)

AI サービスが一時的に利用できないため、復旧後に翻訳を補完します。

A good requirement states one thing that someone can check. It names who does what and under what conditions, and it says what must be true rather than how to build it. The quickest test is to read it back and ask how you would demonstrate it had been met. If nobody in the room can answer, it is a wish. This is about the individual requirement on the page: what a strong one looks like, and how to write one. Which document it belongs in, and how you get the information out of people, are separate jobs. Everything below works one sentence at a time. What do good requirements look like? A good requirement is short, singular and checkable. The widely agreed quality attributes are that it should be unambiguous, testable, necessary, feasible, complete, consistent with the rest of the set, and traceable to a reason. They appear in ISO/IEC/IEEE 29148, the requirements engineering standard, though nobody needs the standard in front of them to use them. Unambiguous. Two people reading it separately build the same thing. Testable. You can describe how you would demonstrate it is met. Necessary. Delete it and something a user or the business needs stops working. Feasible. It can be built inside the constraints you have, not the ones you wish you had. Complete. It does not rely on a fact that exists only in someone’s head. Consistent. It does not contradict another requirement in the same document. Traceable. Six months later you can say who asked for it and why. That list is easy to nod at and hard to apply. Here it is applied to five ordinary sentences. Weak versionWhat goes wrongStronger version Users can export and email reports.Two obligations in one line, so half can fail while the line is ticked.Split it. “A user can export a report as CSV.” and “A user can email an exported report to any address in their own organisation.” Reports must be approved before publication.No actor, so at build time somebody picks one.A finance manager must approve a report before it can be published. The system supports relevant file types.Unbounded set, so the reader decides what relevant means.Uploads accept PDF, PNG and JPEG files up to 10 MB. Anything else is rejected with a message naming the accepted types. A confirmation email is sent when an order is placed.Silent on failure, so the failure path gets invented under pressure.A confirmation email is sent within 60 seconds of an order being placed. If the send fails, the order remains valid and the failure is queued for retry. Admins can manage users.”Manage” hides five behaviours with different permissions.An admin can create, deactivate and reset the password of any user in their own organisation. Admins cannot delete users. Notice what the stronger versions cost. Each needed a decision: which formats, whose approval, what happens on failure, whether deletion is allowed at all. That is the actual work. The writing is the cheap part, which is why vague requirements are so popular. Testability is the test that catches everything else If you cannot describe how you would demonstrate a requirement is met, it is not a requirement. It is a preference, and it should be written down as one so nobody gets held to it in a release review. Two sentences fail this more often than everything else combined. “The system should be fast.” Fast where, for whom, doing what, under what load? Made testable it becomes something like: “Order search returns results in under two seconds for 95% of queries with 200 concurrent users.” Three decisions had to happen to write that. Someone chose the operation that matters, someone chose the percentile, and someone accepted the number. Until then, fast means whatever the reader hopes, and readers are optimistic. “The interface should be intuitive.” This one does not survive being made testable, which is useful information. It can become a usability target with a task attached: “A user who has not seen the product before completes a booking unaided, verified with five participants in moderated testing.” Usually it becomes nothing instead, because someone has to say who the user is and which task counts, and nobody wants to be the person who narrows it. That is the honest part. Making a requirement testable does not improve the writing. It forces a decision someone has been postponing. The vagueness was doing a job: it let a meeting end. The numbers are not really a writing decision either. Somebody has to accept them, and that somebody is rarely the person holding the keyboard. Where getting them all in a room is the obstacle, Projan asks in Slack or Microsoft Teams instead, requesting the figure behind each adjective and recording who agreed to it before the requirement is exported to Jira. Where no target can honestly be stated, write the aim down as an aim, label it, and keep it out of the numbered list acceptance is measured against. Fourteen requirements and three stated aims beats seventeen requirements, four of which nobody can fail. What is a detailed requirement? A detailed requirement leaves the builder with no question they would have to answer by guessing. It closes gaps. It does not specify the solution, and confusing those two is the most common failure on this list. Compare these: “The upload screen must show a progress bar with percentage complete.” “A user uploading a file larger than 5 MB can tell that the upload is progressing and roughly how much remains.” The first is not more detailed. It is a design decision that has been given a requirement number. It commits you to a progress bar even if the engineer could chunk the upload and confirm it instantly, which would solve the problem better for less money. State the how and you remove the chance of something better arriving from the person who knows the system best. Sometimes the how genuinely is the requirement. A regulator mandates a control, a contract names a format, a design system fixes the component. Write those as constraints and say where the obligation comes from. Constraints you can justify are fine. Constraints that turn out to be one person’s habit from a previous job are expensive. On how much detail is enough: stop when the next question a builder would ask has an answer somewhere in the document. Error paths, empty states and permissions are where the missing answers hide, and they are not edge cases in any useful sense. How do you write a good requirements specification? Write each requirement so it can be read, understood and verified on its own, then check the set for contradictions. A specification is not a long requirement. It is a collection of short ones plus the discipline that stops them fighting. One obligation per statement. If the sentence contains “and”, check whether you have written two things that can pass and fail independently. Usually you have. Give every requirement a permanent identifier and never reuse it, even after the requirement is deleted. Reused IDs make old review comments lie. Reserve one modal verb for obligations. The formal convention is shall for mandatory, should for desirable, may for permitted. RFC 2119 defines those key words for internet standards, which is why they appear capitalised in protocol documents. Check the set, not only the sentence. Two requirements can each be well written and still be impossible together. Most product teams do not use shall, should and may, and do not need to. The value is not the vocabulary. It is that obligations become countable: a reviewer searches for shall and gets the full list of what you are on the hook for. Sprinkle it through every sentence including the nice-to-haves and you get the formal look with none of the benefit, which is worse than plain English because it advertises a discipline the document does not have. The conflict check is the step people skip. One requirement says transaction records are retained for seven years. Another says a user who closes their account has all their data removed within 30 days. Both are reasonable, both were written by someone competent, and they cannot both be true. Nobody finds that reading sentences one at a time. The requirements nobody writes down until the last week Non-functional requirements are where most teams are weakest, and the pattern repeats: they surface in the final week, when a load test fails or a customer’s security questionnaire arrives. They were never hard to write. They had no author. Functional requirements have an obvious owner, whoever wanted the feature. Non-functional ones belong to everybody, so nobody drafts them. Five categories cover most of what goes missing. Performance. An operation, a target, a load and a percentile. Availability. An uptime target, a measurement window, and what happens to in-flight work during a failure. The last part is the one people forget. Security. Authentication, authorisation rules, data at rest and in transit, retention and deletion. Retention needs a figure. Accessibility. State a level: conformance with WCAG 2.2 at level AA, for instance. UK public sector digital services are required by regulation to meet a stated WCAG level, which is why their specifications name one and most commercial specifications do not. Capacity and data. Expected volumes, growth, maximum file and record sizes, and what happens at the limit. Accessibility shows best why naming a standard beats describing an intention. “The site should be accessible” cannot be tested, argued about productively or signed off. A named conformance level can be audited by someone who has never met your team, and it forces the decision while it is still a design constraint rather than a rebuild. What are the 7 steps in requirement analysis? There is no canonical seven. Textbooks and training providers each publish their own count and the number is arbitrary. What follows is the sequence that turns one raw request into one written requirement, which is the part most numbered lists skip in favour of the elicitation that comes before it. Methods, stages and handling ambiguity are the other half of the job. Restate the need without the solution. If you cannot, go back and ask. Name the actor. Anonymous requirements get built for a user nobody has met. Ask what would count as failure. The answer becomes your verification method. Split until each statement carries one obligation. Check it against what you already have. Duplicate, contradiction, or a special case of something existing. All three are common past about fifty items. Attach the non-functional limits it depends on. Volumes, response targets, permissions, retention. This is when they are cheap. Record the source and the decision. Who asked, what problem it serves, and what you chose where there was a choice. That is what lets the document survive its author leaving. Where all this lands is a separate decision, and BRD, FRD, SRD and PRD are genuinely different documents rather than the same thing renamed. Frequently asked questions Is must better than shall? Neither is better. Pick one and use it only for obligations. Teams that write shall in every sentence lose the thing the convention exists for, which is being able to count what they are committed to. If your reviewers are business people rather than engineers, must reads more naturally and does the same job. What makes a requirement traceable? A permanent identifier, a recorded source and a stated verification method. You should be able to point at any requirement and say who asked for it, what problem it serves and how it will be checked. Traceability earns its keep when somebody proposes cutting scope, because it shows what breaks. How many requirements is too many? There is no number, but there is a symptom. Once people stop reading the list and start asking a colleague what is in it, the list has outgrown its readers. Split it by capability so each reader has thirty or so to care about, and keep th [truncated for AI cost control]