Minimum Requirements Documentation: A Matter of Context

A colleague asked me about the kinds of documentation the team might need for their stories. He wanted to know what a large geographically distributed team might do. What was reasonable for the stories, the epics, and the roadmap? How little could they do for requirements documentation?

I start with the pattern of Card, Conversation, Confirmation when I think about requirements and how much documentation. I use the guideline: If I can't write large enough on the front of the card to see, my story is too large. I don't use larger cards. I break the story.  That's one way to create minimum documentation—break the story into usable pieces.

As with all interesting questions, this depends on the team's context. Here are ways to think about your context for how to create minimum requirements documentation:

How much does the team collaborate?

Too many distributed teams operate as people in silos, handing work off to each other. If you don't have enough hours of overlap, it's true, you need to hand off work.

If the team hands off work, they're working in resource efficiency, not flow efficiency. And, they need a lot of description of what the requirements are because they aren't collaborating as a team.

Note: In From Chaos to Successful Distributed Agile Teams, Mark and I recommend any other approach than an agile approach if you don't have enough hours of overlap. See Manage It! for ways to use lifecycles other than waterfall or agile.

Are the requirements phrased as tasks or problems to solve?

Let's assume that the product owner writes the requirements, and probably alone. (That's not a good idea, but I think it's this team's reality.)

Note that when the PO writes alone, the PO is not following the pattern of Card, Conversation, Confirmation. The reason that pattern exists is to create collaboration between the customer and the team. Because this team already doesn't have collaboration time, it's quite difficult to use an agile approach that depends on collaboration.

If the PO writes stories or epics as problems to solve, the PO manages some of the documentation effort. That's because the PO is at least halfway answering the “why is this important” question. If the PO adds acceptance criteria to each story and epic and the team agrees on release criteria at the various levels, the team might be close to

If the PO writes functional requirements, the team has no idea why this is a valuable requirement. They can't use their problem-solving skills to refine and understand the real problem to solve.

My experience: teams who don't understand the real problem require a lot more documentation.

How available is the product owner?

If the PO is not very available to the team (distributed or not), the team needs much more documentation.

Agile approaches assume a collaborative approach, including with the PO. Why does anyone think any agile approach would work without collaboration?

Who needs to see roadmaps and for what reasons?

Too often, I see larger organizations think of roadmaps as guarantees of when they will get which feature.  This is legacy thinking, where the organization thinks they won't get a chance to replan until this project is over.

No, agile projects can release as often as they can get to done. I like one-day or smaller stories. New teams often have to work to get there. But why demand a roadmap more than a few months in advance? (See my roadmaps series.)

Base Requirements in Collaboration

My colleague works in an organization where the teams are doing their best to use an agile approach, often Scrum. The managers think an agile approach is a Silver Bullet. It's not. An agile transformation is a cultural change and requires the managers become active participants. Mere “allowance” of an agile approach is not enough.

The question my colleague didn't ask: is an agile approach right for this team? Maybe. Maybe not. A team who hands off work to each other, as in the image at the top of this post, barely collaborates.

We wrote a lot about this in From Chaos to Successful Distributed Agile Teams. Teams who are not organized for team-based collaboration—never mind customer-based collaboration—rarely benefit from an agile approach. I often recommend an incremental approach instead.

How much documentation does your team need for its requirements (for anything)? It depends on your context. These questions might help.

Leave a Comment

Your email address will not be published.

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: