Agile Requirements Documentation – What’s Really Needed?

During agile training sessions, the most common question I get is, “Can you PLEASE just tell me what I need to document as an Agile BA?”

So, let’s clear up this up once and for all!

The answer is NOT simply user stories and acceptance criteria, or a traditional requirements document. Agile is just not that simple. This answer would focus on the wrong thing—output. Instead of focusing on output, it’s the outcome and the path you take to get to the outcome and outputs that’s important.

The reality is, your job as a BA isn’t to document, and it never has been! Seriously. Even when doing waterfall or traditional approaches for requirements, the BA role is about facilitating decision making and facilitating future state discovery. Documentation is the output of all of this. Yes, documenting is part of the job, but it’s not the goal of the business analyst role, no matter what approach the team is using.

Start With The Why.

I am not a “no documentation” zealot, but I am passionate about ensuring that what we create is valuable. Let’s ask ourselves two questions about the documents we create: “What is the purpose of the document and why is the organization willing to pay for it to be created?”

Requirements-related documents cost organizations lots of money, so we need to be able to answer these questions to get the right content documented. We want to avoid wasteful documentation as well as avoid the endless spin created by team dynamics that need a memory of what was discussed already.

When teams transition to agile, they often try to make a concentrated effort to look at documenting less; and this is a good thing to evaluate in the spirit of cutting out waste and focusing on value. When teams are going through this I often see a lot of wasteful documentation teams say THEY MUST have.

Here are the arguments I frequently hear for excessive documenting on agile teams:

• My developers won’t start until its documented in this detail.
• The QA/Testing team requires this much documentation.
• We send the document offshore, so it must be a detailed document.
• We are working with vendors so contractually we need to send them a document of detailed requirements for the whole project.
• We are doing the development in an agile way, but not requirements too.
• We need the requirements documented for training purposes.
• We need the document to remember what we are working on.
• We need the document for compliance.

I will provide my perspective on these arguments, but first we need to cover three important pieces of a healthy agile mindset and environment.

Apply Agile Principles And Working Memory Concepts.

An agile approach enables teams to document less and increase speed while reducing costs. Here are the three agile principles that help teams reduce documentation:

1. Limited WIP (work in progress)
2. Small cross-functional teams, where hand offs are minimized to complete the work
3. Co-located teams (It’s possible to be agile with distributed teams, if teams leverage the facilitation skills, techniques and tools needed to make this work.)

It all comes down to “working memory” and leveraging the working memory of the team to reduce the dependence on documentation.

When a team has Limited WIP, they only work on one or a few things at once. There is less to remember because there aren’t days or weeks between discussions while you work through dozens of topics. With this intense focus, a small cross-functional, co-located agile team has enough working memory capacity to track details with minimal documentation. When a team is leveraging these principles, it feels strange and wasteful to stop and document unless the team agrees it is needed to help them move forward.

Working memory is a key to the puzzle and working memory is maximized when there is limited WIP, small teams and co-located teams. If your organization compromises on any of these, then the working memory of everyone is compromised. Work slows down while teams document to help them remember as they switch between too much work in progress.

What Should Be Documented?

Documentation in agile is “living” and should be updated as the team need to update it. Think of it as a living asset the team uses that grows, gets pruned, gets trimmed and grows some more.

A small, cross-functional team with limited WIP, should document the following:

• Product Vision: The team needs a shared understanding and reminders of the direction they are going. It should be visible too all so that it is pointed to and discussed daily as the details emerge.
• Product Roadmap: The team needs a visual representation of the direction they are headed to achieve the vision and desired outcomes. And, it gets updated regularly!
• User Story Map: The team needs to see the big picture of the user stories from a user journey perspective—to see the forest through the trees of the user stories of a product. And, it gets updated regularly!
• Placeholder for the Conversation: The team needs a way to capture past conversations or hold a place for future conversations. This usually includes user stories and some acceptance criteria.
• Analysis Assets: The team needs to SEE conceptual and analytical models. These visuals help the team remember the big picture of the process, people, technology, rules and data pieces of the project. These are things like: story maps, scope diagrams, decision tables, ecosystem maps, data flow diagrams, etc. These are visual—hung on the wall so teams can quickly jump up and huddle to discuss how a user story relates to all of them, and they are updated as often as needed.

Remember to keep documentation as simple as possible. Choose a format and level of detail that allows change and delivers just enough value to keep the team moving forward in the right direction.

What About Compliance, QA, Vendors, Offshore Teams, Training, Etc.?

OK, back to all those arguments teams use to rationalize excessive documentation. When you focus on limited WIP and small, cross-functional, co-located teams, these are the agile-minded responses.

• My developers won’t start until its documented.
• They should be part of the team, not a hand off
• The entire team needs a shared, limited and focused WIP
• The Product Owner and team need to see working product quick to give feedback to the developers, the more feedback loops, the better the product will be.
• A quality conversation about a small piece of work is enough to get started, if not, then the conversation may not be on track.
• The QA/Testing team requires the document.
• They should be part of the team, not a hand off
• The entire team needs a shared, limited and focused WIP
• A quality conversation about a small piece of work is enough to get started, if not, then the conversation may not be on track
• We send the document offshore, so it must be a detailed document.
• They should be part of the team, not a hand off
• The entire team needs a shared, limited and focused WIP
• A quality conversation about a small piece of work is enough to get started, if not, then the conversation may not be on track
• We are working with vendors so contractually we need to send them a document.
• They should be part of the team, as needed to account for a more collaborative work style rather than hand offs
• Limit the WIP you give them, force them to work on just a little at a time and allow you to provide frequent feedback.
• We are doing the development in an agile way, but not requirements.
• If requirements are not agile too, then how to we know we are building the right thing?
• Requirements not being agile compromises actual agility to change priorities quickly and take in requirements change for strategic advantage.
• Just in time requirements for the most important pieces with a limited WIP maximizes the ability for the organization to learn and change quickly without leaving work mid-progress or waiting for a large piece of work to complete to get to the hottest priority.
• We need the requirements documented for Training purposes.
• The solution design is flawed if you need to train your users on how to use the application. Technology of today and tomorrow will no longer support this type of design.
• There are faster ways to create training documentation than using spec documents. Work as a team with a limited WIP to get the inputs to the trainers that they need.
• We need the document to remember what we are working on.
• Too much WIP! Limit WIP and see less documenting needed.
• Focus on finishing one or few pieces at a time, not on starting more work.
• We need the document for compliance.
• Most teams are documenting too much for compliance compared to what compliance actually requires.
• If you really dig into what compliance requires, lightweight documentation usually works just fine
• Also consider documenting what was built rather than before it is built so that the team does not have to do rework when things change.

Essentially, I’m asking you to adopt an agile mindset and advocate for limited WIP and smaller teams that reduce the need for documentation, reduce costs and accelerate product/solution delivery.

If your organization has compromised these principles, then working memory challenges are likely driving your teams to document more. That is okay, as long as the team and organization realizes the value of the document and is consciously choosing to slow down outcomes and results due to the choice of compromising the agile values.

Remember that your role as an agile business analyst is not about documentation. It’s about facilitating good and timely decisions, and guiding stakeholders to discover a future state that delights the end user.

#linkedinlearning #agile #requirements