EU MDR (2017/745) Compliance Automation for Technical Documentation & Traceability
Automate EU MDR technical documentation and GSPR traceability for medical...
How to Write Better Requirements: A Practical Guide That Actually Works
Listen to this blog
Why Most Requirements Fail (And What to Do About It)
You’ve seen it happen. Three months into a project, the team is building something that doesn’t quite match what the business asked for. Meetings multiply. Scope creeps. Budgets balloon. Somewhere along the way, the requirements document became less of a guide and more of an artifact nobody trusts.
Here’s the uncomfortable truth: most requirements problems aren’t technical—they’re human. Requirements engineering involves engineering knowledge, skill in dealing with people, and experience in assessing business realities like competition and political pressures. Get the human side wrong, and no amount of technical brilliance will save the project.
The good news? Many of the traps that ensnare the unwary can be avoided by applying simple guidelines. Projects that start out well, with clear and accurate knowledge of the goals and needs of their users, have the best possible chance of success.
This guide walks you through the practical techniques to get it right the first time.
The Single Most Important Principle
Before we dive into structure, syntax, and checklists, let’s anchor on the one principle that matters most:
Understand and agree upon what users want before attempting to create solutions.
Finding out what is needed instead of rushing into presumed solutions is the key to every aspect of system development. Most technical problems can be solved—given determination, patience, a skilled team, and a well-defined problem to solve.
That last part is what gets missed. Teams jump to solutions before they’ve genuinely understood the problem. Don’t be that team.
What a Requirement Actually Is
Let’s start with the basics. A requirement must be a complete sentence. Not a single word. Not a phrase. Not a collection of acronyms and abbreviations.
For a requirement to be understood, it must be a complete, correct sentence with two essential parts:
Subject + Predicate = Requirement
Here’s an example:
The reader shall be able to understand the requirement.
The subject is “the reader.” The predicate is “understand the requirement.” The phrase shall be able to joins them together to form a complete requirement.
The Magic Word: “Shall”
Consistent use of the verb to be solidifies the link between subject and predicate. But in requirements language, shall carries enormous weight. It signals that this sentence is a requirement that must be followed or adhered to.
Other “shall” words include will and must—both signify a mandatory condition. For example:
The reader must comply with this documentation convention.
Less restrictive words denote non-mandatory or optional requirements. Should, may, or phrases like if it is desired that indicate something desirable but not mandatory:
The document should take no longer than one hour to read.
Notice the difference. “Shall” is non-negotiable. “Should” is preferred but not required. Mixing these up creates confusion downstream when QA tries to verify compliance.
The Anatomy of a Good Requirement
Each user requirement should have four key components:
- A user type who benefits from the requirement
- A defined, desirable state for the user to reach
- A person responsible for implementing the requirement
- Metrics or some mechanism to allow a test to be written against the requirement
Consider this example:
The order entry clerk shall be able to complete ten customer orders in less than an hour.
Break it down:
- User type: “the order entry clerk”
- Desired state: completing ten customer orders
- Performance criteria: in less than an hour
This requirement is clearly measurable. You know exactly who it serves. You know what success looks like. You can write a test against it. Every single requirement should follow this pattern.
The 7-Point Checklist for a Good Requirement
Before locking in any requirement, run it through these questions:
- Is it correct? (Asks for something possible, do-able, legal)
- Is it complete? (A complete sentence)
- Is it clear? (Unambiguous and not confusing)
- Is it consistent? (Not in conflict with other requirements)
- Is it verifiable? (Can we determine that the system meets it?)
- Is it traceable? (Uniquely identified and can be tracked)
- Is it feasible? (Accomplished within cost and schedule)
Other criteria worth striving for:
- Is the requirement modular and able to stand alone?
- Does it have a reasonable priority?
- Is it genuinely a user or system requirement, not a design constraint?
- Is its source documented?
You’ll find that quite soon, you do this automatically whenever you see a requirement. It becomes second nature.
8 Practical Guidelines for Writing Requirements
These guidelines apply to any requirement you write. Use the example of an aircraft system to keep things consistent:
1. Define one requirement at a time
- The pilot shall be able to control the angle of climb with one hand and feel the angle of climb from the climb control.
- The pilot shall be able to control the aircraft's angle of climb with one hand.
- The pilot shall be able to feel the angle of climb from the climb control.
2. Avoid conjunctions (and, or) that make multiple requirements
When you see AND or OR, you almost always have multiple requirements hiding in one. Split them.
- The navigator shall be able to view the aircraft's position relative to the route's radio beacons and the aircraft's position estimated by inertial guidance.
- The navigator shall be able to view the aircraft's position relative to the route's radio beacons.
- The navigator shall be able to view the aircraft's position estimated by inertial guidance.
3. Avoid let-out clauses (unless, except, if necessary, but)
- The fire alarm shall always be sounded when smoke is detected, unless the alarm is being tested or the engineer has suppressed the alarm.
This kind of escape clause makes testing nearly impossible. Stick to definite statements.
- Each cabin crew member shall be provided a rear-facing seat.
4. Use simple direct sentences
- The pilot shall be able to view the airspeed.
No need for circumlocution. Plain, direct language wins.
5. Use a limited (600-word) vocabulary
Especially if your audience is international, plain language matters. There is no need to use words like reconfigured when changed will do.
- The airline shall be able to change the aircraft from business to holiday charter use in less than 12 hours.
6. Identify the type of user who wants each requirement
Start every requirement with a clear subject:
- The navigator shall be able to...
7. Focus on stating what result is to be provided for that type of user
Don’t describe the implementation. Describe the outcome:
- ...view storm clouds by radar...
8. Define verifiable criteria
- ...at least 200 miles ahead.
Now testers know exactly what to check. No ambiguity.
User Requirements vs. System Requirements: Know the Difference
This is where many teams stumble. User requirements and system requirements differ in what they define and how they define it.
| User Requirements | System Requirements |
|---|---|
| Description of the problem | Abstract solution |
| In user language | In developer language |
| Organized by goals | Organized by functions in a hierarchy |
| Subject: a type of user | Subject: the system or subsystem |
| Defines what the user gets | Defines what the system does |
| Owned by users | Owned by developers |
What Is a User?
A user is someone involved in using the system when it is actually working. Using is not restricted to mean only operating a system. Anyone involved in maintaining, interacting with, the approval cycle, or even checking safety are all users—but a safety inspector is certainly not a system operator.
Examples of users include:
- An order entry clerk
- A shipping and handling clerk
- A salesperson
- A department supervisor responsible for order approval
- The customer who places the order
Writing User Requirements
The main task of a user requirement is to help users express their needs in writing. For an engineer with a technical or software bias, getting into your users’ way of thinking is difficult. Technical people typically come from a range of professions, but they usually have their own language and concepts.
Requirements are hard to formulate exactly, and you may need several revisions to get them just right. Start with a draft and sharpen the wording later. Initially, just aim to get the basic intention down on paper.
Writing System Requirements
System requirements look at the solution and commit to specific technologies while still leaving space for designers to work. They define the system without going into the detail of design.
Just as you make each user requirement begin with a kind of user who wanted that particular result, you make each system requirement refer to a specific function:
The order entry system shall provide the ship date of ordered items.
It is then easy for the order entry designers to select only their requirements to work on, not distracted by requirements of other subsystems.
Common Pitfalls That Sink Projects
After all that, let’s look at what to avoid.
Pitfall 1: Ambiguity
Avoidance of ambiguity is one of the subtlest and most difficult issues in writing requirements. Try to write as clearly and explicitly as possible.
Dangerous ambiguities can be caused by the word or, and also by many more subtle errors:
The same subsystem shall also be able to generate a visible or audible caution/warning signal for the attention of the co-pilot or navigator.
Which subsystem? Is the signal to be visible, audible, or both? Is it both caution and warning, just caution, or just warning? Is it for both the co-pilot and the navigator, or just one of them?
You can see how this single sentence creates a dozen different interpretations. Multiply that by hundreds of requirements and you’ve got chaos.
Pitfall 2: Vague, Undefinable Terms
Many words used informally to indicate system quality are too vague for use in requirements:
- user-friendly
- versatile
- flexible
- approximately
- as possible
Requirements using these terms are unverifiable because there is no definite test to show whether the system has the indicated property.
- The print dialog shall be versatile and user-friendly.
- The OK status indicator lamp shall be illuminated as soon as possible after the system self-check is completed.
What does “as soon as possible” mean? 1 second? 30 seconds? Specify it.
Pitfall 3: Expressing Possibilities Instead of Requirements
Suggestions that are not explicitly stated as requirements are invariably ignored by developers.
Watch out for: may, might, should, ought, could, perhaps, probably.
- The reception subsystem probably ought to be powerful enough to receive a signal inside a steel-framed building.
If it’s important, state it as a requirement. If it’s not important, leave it out.
Pitfall 4: Wishful Thinking
Engineering is a real-world activity. No system or component is perfect. Wishful thinking means asking for the impossible.
Watch out for terms like:
- 100% reliable
- Safe
- Handle all unexpected failures
- Never fail
- Upgradeable to all future situations
- The gearbox shall be 100% safe in normal operation.
- The network shall handle all unexpected errors without crashing.
These aren’t requirements—they’re wishes. And wishes can’t be tested.
Pitfall 5: Designing the System
Requirements specify the design envelope. If you supply too much detail, you start to design the system. Going too far is tempting for designers, especially when they come to their favorite bits.
Danger signs include names of components, materials, software objects/procedures, and database fields.
- The antenna shall be capable of receiving FM signals, using a copper core with nylon covering and a waterproof hardened rubber shield.
That’s a design specification, not a requirement. Specifying design rather than actual need increases the cost of systems by placing needless constraints on development and manufacture. Often knowing why is much better than knowing what.
Why Structure Matters as Much as Wording
A medium-sized project typically demands hundreds of requirements. Readers can only understand these fully when the requirements document is organized logically. The best structure for user requirements follows the natural patterns of use, structured like a scenario or use case.
Everyday language is the only medium that users and developers share. Everyone can immediately understand requirements written this way—therefore you might think writing in plain language would be the ideal way to define user needs. But simple text isn’t good at showing how different user needs fit together. After all, you want to make a system, not a mass of unrelated functions.
The structure must give readers insight into the text. A good structure shows the requirements at different levels of detail and allows readers to focus on one section at a time.
You probably need three levels of headings to organize the requirements. Try not to use many more than that. Your structure should explain itself.
For an aircraft, that structure might look like:
- Prepare Aircraft for Flight
- Fueling
- Cleaning
- Loading baggage
- Loading meals & supplies
- Loading passengers
- Pre-flight Checks
- Instrument Failure
- De-icing
- Operate the Flight
- Taxiing to runway
- Takeoff
- Flight
- Control
- Navigation
- Passenger Service
- Landing
- Docking
- Maintain Aircraft
- Daily Servicing
- Major Servicing
Notice how main headings break down into their own lists of activities. Significant exceptions are listed where they would be detected. Related activities are grouped logically. This is a structure users can navigate.
Where Modern Requirements Fits In
Once your requirements library grows beyond a handful, managing them in static documents becomes nearly impossible. You need:
- Real traceability between user needs, system requirements, design, and tests
- Version control that captures every change with rationale
- Attributes for each requirement (priority, source, status, verification method)
- Review workflows that route changes to the right stakeholders
- Reporting that answers questions like “show me all high-priority requirements from the pilot on the flight control sub-system”
This is exactly where Modern Requirements earns its place in the toolkit. Built natively into Azure DevOps, it transforms requirements management from a documentation chore into a living, traceable system. Teams can capture requirements with rich attributes, link them to test cases and work items, run review cycles, and maintain a single source of truth that scales from 50 requirements to 50,000.
The principles in this guide—complete sentences, clear subjects, verifiable criteria, proper structure, change tracking—are exactly what Modern Requirements is engineered to enforce and accelerate.
Putting It All Together: Your Action Plan
If you take nothing else from this guide, take this checklist:
- Start writing requirements now. Don’t wait for perfection. Get a draft on paper and iterate.
- Produce a document at the soonest moment, then stimulate immediate feedback.
- Clean up the requirements as you go—remove design and multiple requirements.
- Define an outline structure first, or do it as you go along.
- Brainstorm and hold internal reviews continually.
- Expose drafts to users. Rapid correction is much better than analysis by experts alone.
- Run every requirement through the 7-point checklist.
- Watch for the 5 pitfalls. Ambiguity, vague terms, possibilities instead of requirements, wishful thinking, and design creep.
- Separate user requirements from system requirements. Different audiences, different purposes.
- Use a tool that grows with you. Spreadsheets fail at scale. Plan for the requirements management infrastructure you’ll need at 500, 5,000, and 50,000 requirements.
Final Thought
Writing better requirements isn’t about following a template. It’s about communication. Requirements are the vital communication line between users and developers. System engineering is a human issue, which works only when everyone involved cooperates to solve problems.
Projects succeed when they stay focused on results, so that whatever is developed aims only to satisfy the need and deliver only what users want. This is only possible when users’ needs are clearly defined, and their problem is fully described in writing.
So start now. Keep it small. Correct it at once. The discipline pays for itself many times over.
Table of Contents
Recent Articles
Audit-Ready DevSecOps for Financial Services: Building Compliance Into Every Release
Learn how banks, insurers, and fintechs build audit-ready DevSecOps that...
Microsoft, GitHub, and Azure DevOps: What the Shift Really Means – and Why Modern Requirements is Built for What’s Next
Explore how GitHub and Azure DevOps work together in a...
