Documenting Agile Requirements

Dec 28, 2019

In a previous blog I discussed how to write a user story, and how to structure the product backlog. This is only part of how we manage requirements, and recall that I also restated part of the agile manifesto, one of the priorities being that we value:

"Working software over comprehensive documentation"

This is the part that often causes much confusion, with some people saying that we don't have documentation in agile. We do, it's just done differently.

What documentation should we produce?

Often it can seem like that documentation was created for the sake of it. If you were the one diligently creating it you also knew that most of those people named in the document would not read it.

We now have a Product Requirements Document (PRD) but a name change is the least of the differences between this and its closest relative, the Business Requirements Document (BRD). Make no mistake, a user story or PRD is not just a replacement for the BRD. Before talking about the PRD, let's recap user stories.

User stories are our building blocks

If you read the previous blogs you will recall that that our user stories capture a requirement from the perspective of a class of user. However. these are high level and only form the basis of a discussion between those who state what is needed and those who build it.

We will then develop the acceptance criteria that define what 'done' would look like to someone testing that the feature has been developed. After that we would then be able to define some tests.

What about 'requirements'?

Requirements define what a development team needs to build and are not stated from a user’s perspective. These can detail every screen, label, messages, rules, data mapping files, and more. We can include wire frames and some screenshots / mock-ups. Workflow can also be provided such as in a flow diagram or a series of screens depicting transition changes.

There are some similarities with what the Functional Specification Document (FSD) aims to produce, but a difference is that we only provide these details for the user stories that we want to develop. An FSD can be very large and verbose, and is done well in advance, covering the entire system, is often hard to read and susceptible to change.

The Product Requirements Document

Teams and projects are different, and PRDs are not always written the same, but if I have to describe a template, it would look something like the below:

Release, status and Stakeholders

The release date, scope (included / excluded in this release), and named product owner and other key stakeholders.

Background and Objective


This should explain the customer problem that will be solved. It establishes the high-level purpose of the product or features.


The list of user stories, and for each a:

  • Description - the user story name
  • Purpose -  what the user wants to accomplish
  • User problem - why there is a problem being addressed
  • User value - the value to the user of completing the story
  • Assumptions - any business, user, or technical assumption
User flow and design

A user journey describes at a high level of detail what a user does or experiences when interacting with a system to achieve an overall goal.

A user flow describes the specific actions taken to accomplish a goal at a specific stage within a user journey. Ideally this will include an outline of the user flow and some mock screens to accompany it will 


There must be a way of measuring the success of the feature.For example:

We believe that supporting multiple languages will increase customer acquisition by 20 percent.

Other examples are

  • Percent of users who interact with the feature
  • How long it takes to interact with the s
  • How often each feature is being used
  • How long users spend interacting with the feature
  • Abandonment rate
Discussion notes The discussions that have been had with the experts should be noted, particularly and questions or key decision.

Future work

In to avoid technical debt*, the longer term intentions should be communicated to the development so that they can make better, long term decisions.

* Technical debt = the effort of doing additional rework caused by choosing an easier, but limited solution now instead of using a better approach that would take longer How the feature may evolve


If you use JIRA, there are some great techniques that can be used to track and develop user stories, but for a PRD you will also need to use Confluence. Discipline is needed in agile as much as it ever was for other styles of project. As is experienced by some, agile should not be like the Wild West.

When should we produce a PRD?

That's a good question, and if the user stories really are atomic, and well described, I would try to avoid writing a PRD but as a challenge becomes more complicated, there may be value to doing this.

Like most documents, the skill of writer will be important in making the document understandable. The usual problems will also still exist, these being; the document not being maintained, and getting people to actually collaborate using it.

Shall we talk?

Lets have a conversation

If you would like to know more about how I've helped to transform some the world's biggest and well known businesses, across diverse industries in the United Kingdom, Singapore, and Hong Kong, then please drop me a line. Let's have a chat and I'll buy the coffee!

Multiple screens showing responsive web developement next to a hot drink for a meeting

Turn your idea into digital reality

Many of my clients requiring web design have been small or start up businesses and need a lot of guidance. I love these kind of projects as I feel I can be a part of a new and exciting business from the very beginning!

What can I call you?
Enter your email address
It would be nice to tell us why you are contacting us!
To prevent spam mail, enter the sum of the spam captcha