Clear and unambiguous software requirements

You cannot escape the need for clear requirements.

Agile without clear requirements is as bad as a poorly formed waterfall project.

And ‘placeholders for conversations’ are nothing more than an idea that is ill-formed, and at worst, not even that.

Many user stories are just too vague and open to interpretation.

What’s missing? All the context.

A well-defined user story should be accompanied by sufficient context for the implementer to make the right decisions. This includes, but isn’t necessarily limited to, one or more of the following:

• 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

Each story’s performance attributes and non-functional requirements (eg. accessibility, interoperability, redundancy) should also be included.

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

Including technical details that would not normally reside in a user story, such as API endpoints and message schemas, is a judgment call. Weigh up whether the additional detail adds to the story’s readability or detracts from it.


Good user stories are hard to come by, but it doesn’t need to be like this.

User stories start their life as one-liners in a bulleted list, however they need to become more thoroughly defined in the period leading up to implementation.

Someone knowledgeable, like a business analyst, can use the above as a guide to determine what information is most relevant and helpful to include in each user story.

Drafting good user stories is often a team sport, with clarifications and detail added through successive refinement and possibly by different team members.

Adequate documentation also supports requirements traceability, an essential part of software development.

And a good “definition of ready” within the team goes a long way, too.


Documentation for any distributed Engineering team (not just those outsourced and offshored) is often more than you would expect for co-located teams.

I have seen people collaborate globally, across time zone differences, very effectively. But to do that, you have to shift to mostly written forms of communication.

The ability to asynchronously communicate becomes necessary when there are large timezone differences. This also, most importantly, requires the offshore team to communicate clearly and effectively.

Jeff Sutherland in “The Scrum Papers: Nut, Bolts, and Origins of an Agile Framework” gives an excellent example of this, namely:

“St. Petersburg staff likes a detailed description because the system is a comprehensive and complex system designed for specialized librarians. As a result, there is a lot of knowledge that needs to be embedded in the product specification.”


Even well-documented requirements cause problems due to misinterpretation, ambiguity, or incorrect assumptions.

Sutherland raises this point in the St. Petersburg’s scenario, saying:

“A lot of questions result after receiving the document in St. Petersburg which are resolved by in daily Scrum meetings, instant messaging, or email.”

This is why I’m a huge advocate of refinement, because if you devote time to this crucial activity, you stand more chance of building what is required and less chance of re-working it down the line.