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 Lyntev. Updated on .
About 5 minutes to read.

The answer starts with the sourceApproved information, defined access and a verifiable answer.

Translation published on . Original Portuguese guide; source revision .

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.

Describe scenarios someone can carry out
ElementCompleted fictional example
RoleSupport coordinator
PreconditionOpen request with no technician yet
ActionSelect an active technician and confirm assignment
ResultRequest shows its owner and records the change
ExceptionInactive 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.

Fictional criteria for assigning a requesttext
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.

Prioritise by need and preserve links to tests
Weak wordingHow to improve it
Have complete reportsName the decision, data, filters and calculation.
Allow everything to be editedSpecify which roles can edit which fields and statuses.
Send notificationsDefine the event, recipient, channel and failure.
Integrate with any systemIdentify 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.

Wellinton Oliveira

Written by

CEO of Lyntev

Technology with context, original analysis and sources you can consult.