How user stories can help you write clear and testable requirements

How can user stories help you write clear and testable requirements?

The way we do it is to always emphasize on writing testable requirements documentation. Read below to learn how.

What exactly is ‘Testable requirements documentation’?

Essentially, all that ‘testable requirements documentation’ means is that whatever you write or instruct is either measurable or actionable in some way.

If you can’t figure out how to write a test case for the requirement, the requirement is not testable. Trying to define some sort of fantastical functionality without grounding it in reality is entirely pointless and a waste of time, so be sure that what you describe is clear, actionable and most importantly, easily understood by testers and developers.

How should I write requirements this way?

At ReQtest we write our requirements in the form of user stories, and user stories are very often written using a template that looks something like this:

As a [stakeholder] I want to [goal] so that [motivation] 

A completed template will look something like the below example:

As a test manager, I want to see status of the requirements so that I can plan testing.

The concept of the stakeholder describes for whom something should be done, the goal describes what to do and the motivation describe the ‘why’ in ‘why are we doing this?’

Many other forms of requirements documentation lack descriptions of the stakeholder and the motivation, but by highlighting these parts, the requirement becomes clearer for all involved.

For example, your developer will better understand even more about the purpose of the feature than if they were simply instructed to ‘write this or that function’.

How does this help me?

User stories help us to focus on the user’s needs rather than on solutions and technologies. For example, here at ReQtest, our testers participate in the requirements discussions.

Sometimes the product owner will draft requirements and let the testers refine them, thus making sure that the testers really take part in the requirements writing and therefore ensuring that our requirements are testable.

But these user stories are too short!

On occasion, you will hear criticism that the user stories are too brief. If you feel you need more text, it is perfectly fine to supplement user stories with use cases or ordinary textual requirements.

Some people think that user stories are too repetitive, maybe because all user stories are somewhat alike, for example, “for this kind of role I want to do this so that I achieve that”. This may be so, but then again, the purpose of documentation is not poetry or prose; it is to write clear requirements. What’s most important is that the requirements documentation is clear and therefore it doesn’t matter if the text gets a little tedious.

Here at ReQtest we complete user stories with communication, which to be fair is possible because the whole team sits together in the office.

On occasion, the product owner will write traditional requirements and once the developers detail the requirements so as to be able to estimate the development effort, they themselves will write detailed development tasks. This documentation will always be produced for the current sprint only.

What else will I need?

We often draw sketches, known as mockups, to clarify the user interface requirements and make sure that the flows are logical. There are many tools you can use for this, but we use Photoshop or tools like Balsamiq Mockups. Drawings are part of the requirements documentation and later on in the dev cycle will also be used for usability testing.

Usability tests are used to evaluate the usability for all newly developed features.

One thing that you will not get for free when working with user stories is the system documentation. If you write requirements with other techniques, such as use cases, there may be some text in them that can be recycled to the system documentation.

Our system documentation consists of the database model, automated test cases, well-written code with comments and documented business rules. We also carry out a significant part of the development as pair programming, which makes us less vulnerable.

All developers have knowledge about large parts of the system, while having the opportunity to develop within their respective areas, which makes it more exciting for them as well as giving them more responsibility and room to grow their talent as well.