Announcement: All software requirements services are now delivered through Better Software UK.

How to write better software requirements

Expecting developers to magic something from a vague idea or a one-sentence user story isn’t a particularly helpful approach.

Teams with poor software requirements don’t deliver well on them. Remote, outsourced and offshore teams with poor requirements fare even worse. I have never come across an underperforming development team that didn’t also have a requirements problem.

Select a few requirements from your team to inspect. Are they clear and effective? Do they convey the outcome required? Report back and tell me what you find. Follow the guidance below, if you need help assessing the requirements.

Many user stories are just too vague and open to interpretation. What’s missing? All the context.

Developers need a clear understanding of what to do. Some developers tolerate ambiguity better than others. However, they still need a clear understanding of what to do. Experienced developers in small teams and with good access to users require less prescriptive requirements; junior developers, building enterprise software, located in remote teams require more.

User stories should describe what is needed and provide sufficient information for the developer to make the right decisions. Technical design and implementation details are avoided, unless there is good reason to specify them, as the developer’s job is to figure that out.

Things to consider including alongside a user story, when appropriate, include:

  • Background information
  • Acceptance criteria
  • Alternative scenarios
  • Business rules
  • Error handling
  • Illustrations, UI mockups and designs
  • Research data and user feedback
  • Existing product features related to the story
  • Clear directions stating what technical approaches are acceptable
  • Assumptions, constraints, notes

Performance attributes and non-functional requirements for each story (eg. accessibility, interoperability, redundancy) should also be considered.

However, as performance attributes are usually defined for an overall product or product sub-system, it is best practice to define these centrally and reference them from the user stories.

Including technical details such as API endpoints and message schemas in a user story is a judgment call and should probably be included if they enhance the story’s readability.

Regular refinement sessions ensure developers understand the stories and can work without unexpected blockers or the need for unplanned, ad-hoc conversations. Written communication becomes even more important for remote teams and asynchronous working.

Well defined user stories are your best chance of building what is required and avoiding waste and re-work later on.



If you are unhappy with your development team, they may need more detailed guidance.

Clear and effective software requirements can help with this.


Frank Ray Consulting. Software requirements for agile development teams, particularly remote, outsourced and offshore development teams working in financial services.

Get in touch if you need our help

Woking, Surrey, GU22, United Kingdom