How to write software requirements you can verify
A useful requirement explains who needs to do what, under which conditions and how the result is confirmed. This lets you compare proposals, implement expected behaviour and accept delivery against clear criteria. You can start in a simple document if it preserves decisions, versions and specific examples.
By the end, you can:
- Separate objectives from features
- Define rules and boundaries
- Link requirements to tests
Explain the problem and boundaries of the first delivery
Start with the observed problem, affected people and desired outcome. “We need an app” describes a possible solution; “requests have no owner when they arrive through different channels” describes a problem guiding the project. State how the situation was observed and what remains unconfirmed.
Define the first delivery’s scope. In a fictional technical-support example, the system receives requests, assigns owners and tracks statuses. Invoicing and parts management are outside that phase. Microsoft’s implementation guidance recommends making objectives, scope and responsibilities explicit. This boundary lets changes be assessed without treating every new idea as an implicit part of the original agreement.
Describe scenarios someone can carry out
Identify the role, task and reason. “As a coordinator, I want to assign a request to a technician so someone is responsible for the intervention” is a start. Add the initial status, necessary data and output. The name of a button or screen does not replace process behaviour.
Azure Boards’ Agile documentation distinguishes stories, tasks and defects. Use that distinction without depending on the tool: one user need may generate several implementation tasks. Keep the story understandable to operational staff; code details can be linked in a technical note.
| Element | Completed fictional example |
|---|---|
| Role | Support coordinator |
| Precondition | Open request with no technician yet |
| Action | Select an active technician and confirm assignment |
| Result | Request shows its owner and records the change |
| Exception | Inactive technician cannot receive new requests |
Make rules affecting the result explicit
List required fields, permitted statuses, permissions and change conditions. “Assign technician” raises questions: who can change the assignment? Can there be two owners? What happens if the technician leaves the team? The rule needs a business decision before translation into the system.
Define ambiguous terms in a short glossary. A closed request may mean completed, cancelled or rejected; if those cases need different reports, they must be distinguishable. For dates, amounts and quantities, state units and time zones where relevant. Add examples of valid, invalid and missing values, especially in fields imported from other systems.
Write what demonstrates the requirement has been met
An acceptance criterion describes an observable result. Include the expected journey and cases where the operation must be rejected. Avoid criteria such as “works correctly” or “is intuitive”: they do not clarify the approval condition. Use test data without unnecessary personal information.
Microsoft’s test plan connects requirements, preconditions, steps and expected results. A practical form is “given, when, then”. If two users change the same request, define acceptable behaviour: prevent a silent overwrite, request a refresh or apply an explicit rule. The technical team chooses an implementation capable of meeting that contract.
Given an open request without an owner,
when coordination selects an active technician and confirms,
then the request shows that technician and the change is kept in history.
Given a request another coordinator has just changed,
when someone confirms using an outdated version,
then the system warns them and does not silently overwrite the change.Include quality and operational requirements
Beyond features, describe devices, accessibility, performance, continuity and support. “Fast” is insufficient: state the operation, test conditions, data volume and measure to observe. A time target chosen for the project is a negotiated criterion, rather than a universal standard or promise before testing.
Confirm who creates users, recovers access, exports data and handles incidents. Identify integrations, known limits and test environments. If work depends on connectivity, define behaviour when the connection fails. Do not request offline operation without explaining which tasks remain available and how conflicts will be resolved when connectivity returns.
- State the browsers and equipment the team actually uses.
- Define access roles and examples of prohibited operations.
- Agree backups, recovery and maintenance responsibilities.
- Separate first-delivery features from later improvements.
Prioritise by need and preserve links to tests
Classify requirements as essential for initial operation, important or deferrable. Justify priority and dependencies: a report may depend on dates not yet recorded. A list where everything is urgent does not help decide scope when time or investment is limited.
Give each requirement an identifier and link it to the corresponding test. When changing a rule, record the reason, decision and affected tests. Distinguish defects, clarification and scope changes. This distinction does not automatically decide commercial conditions; it provides evidence to discuss what changed and its impact.
| Weak wording | How to improve it |
|---|---|
| Have complete reports | Name the decision, data, filters and calculation. |
| Allow everything to be edited | Specify which roles can edit which fields and statuses. |
| Send notifications | Define the event, recipient, channel and failure. |
| Integrate with any system | Identify specific systems, contracts and operations. |
Use one worksheet per verifiable behaviour
Complete the requirements supporting the main journey first. Review them with someone from operations and someone from implementation. When the team can explain the scenario and test in the same way, there is a useful basis for estimating and building. Keep unresolved decisions with an owner and a date for resolution.
Worksheet for your project
Requirement worksheet Identifier, title and version: Problem or objective addressed: User role and necessary permissions: Initial status and input data: Action and expected result: Rules, statuses and exceptions: Acceptance criteria and examples: Behaviour on error or concurrency: Associated quality requirements: Dependencies and justified priority: Linked test and expected evidence: Open decisions and responsible person: Approval and date:
Sources and criteria
Content prepared with AI assistance and research using technical sources, with checks of the relevant examples and calculations. The references support the guide’s decisions; examples identified as fictitious let you try out the method.
