Walking the requirements documentation tightrope in an agile world

Sherif Mansour
6 min readJul 3, 2013

One of the exciting things I get to do as part my job is talk to a lot of customers about how they build software. I hear about what works for them and the challenges faced by teams as they journey on their mission to build great products. One of the obstacles which often comes up is regarding the tension teams face with documentation in an agile world, particularly around requirements. You’ve gone agile - now what?

Some teams want to put to death the traditional “Product Requirements Document” (PRD). The “traditional” PRD? I think you might know what I’m talking about: Ten, twenty… sometimes thirty page Word documents with over fifteen sections which scream “Fill me or the document isn’t complete!”. These documents are typically passed around teams inboxes like a game of ping pong, making finding the latest version of the document harder than looking for “Where’s Wally”…and eventually they’re thrown over the fence to an engineer to deal with.

What does the requirements gathering process look like in an agile world? How does Atlassian do product requirements? What does the PRD look like for agile teams? Does it still exist? To help navigate your team through these challenges, I thought I’d take a moment to share with you our experiences within the product management team here at Atlassian. Lessons we’ve learnt: what we use, what works for us and challenges we’ve faced.

We try not to

Before we go any further, I must say something which may surprise you: our first thought is to try and avoid writing requirements documents. If we’re breaking down user stories into small, digestible descriptions of user scenarios and problems, we typically want to be raising them straight into JIRA. This is really what we strive for. Creating documentation to track what is often small enough to put into our backlog, already well defined and agreed upon may appear to be valuable but often outweighs the time and cost of creating and maintaining the documentation.

Whatever floats your boat

The agile manifesto should remind us that we don’t always have to do it the “traditional” way.

As product managers, we should be doing whatever is required to tell the story of the customer. Try different things: experiment, explore, then do what works best for you and your team in the context that you might be working in. What do I mean by this?

  • If it means you can have several discussions and sketch something on a bit of paper - then do it.
  • What if you could get everyone (including the customer) in a room and do a user story mapping exercise? If that communicates the problems well, then you probably don’t need to go much further.
  • Or what if you can visit the customer in their context as they use your product? Could you get your engineers and designers to sit next to the customer to listen and observe their problems?
  • Another option would be to grab the product triad (a Product Manager, Engineer and a Designer) for a quick stand-up, sketch, discuss and make some quick decisions on the spot.
  • Need to explore some more? Try running a workshop where you gather key stakeholders and do lots and lots of whiteboarding or even paper prototyping to dive deep into understanding the problems you are trying to solve and how you could solve those problems.

You get the idea. It’s important that we consider writing an requirements document just one of many ways we can help define and communicate customer problems.

So when do you need to document?

In my experience, I’ve typically found documenting things can be helpful when the size of perceived problem is fairly large, there is inherit complexity or history involved with the product or feature we are working with. If I were to draw a ”getting down on paper” scale, it might look something like this:

“Getting it down on paper” - a rough guide for when you’ll need more definiton.

As product complexity increases, so does the initial level of definition required. Let me share with you two brief examples to illustrate this:

A couple of years ago we launched Team Calendars - a collaborative calendaring solution to help teams plan and communicate people, projects and team events. This was a brand new add-on for Confluence. Developed from scratch. No legacy to deal with. Our level of requirements definition, in terms of documentation, was very thin. I just went looking in our internal Confluence space and we barely put pen to paper in terms of requirements. We did have a page with some basic user stories, but it was mostly covered with lots and lots of visual designs and mockups. Most of our effort was on a prototype where we spent a lot of time in verbal discussions, demos and dogfooding the prototype on a weekly basis. Level of requirements documentation: low, very low. Other techniques that helped us define what we were building: Mockups, visual designs, prototyping and regular user testing with customers for our feedback loops.

Contrast this effort to something like our initial version of the Page Layouts feature in Confluence. What was the bare minimum we could ship which provided value to our customers? As we fleshed out the concept it turned out there was a lot we could do! We had a page where we tracked, defined and discussed our main user stories. What we found as we fleshed it out was that our “not doing” / “out of scope” list kept growing. This helped our team stay focused on the most viable solution we could ship. In addition, because the feature was landing in an editor with a large set of existing features, there was a lot for us to think about. How would this work with PDF or HTML exports? How would the interaction work for copy-pasting page layouts? Would we need to change email notifications to reflect a page layout? What about resizing them? What was the minimum required for now and what could we do later? There was a lot more to think about. With page layouts, a lot of the discussion came into play when other features intersected with what we were trying to do.

We need to remember that software doesn’t age very well. And when it does, there are often many more considerations, assumptions, constraints and other variables you need to think about other than a simple user story in your backlog. In those scenarios, we usually end up collaborating over a Confluence page which represents multiple user stories related to the feature. This enables the team to put down all their thoughts around the user problem in one central location. What we find that this process of “getting it down on paper” helps us walkthrough the process of taking what is often thought of as a large, complex problem and breaking it into smaller, more deliverable, focused user stories that can be tackled. This process eventually leads to multiple broken down stories in our backlog.

Your turn

About to write your next PRD? Why not talk to your team about how the requirements and definition gathering process is going. Reflect on the different techniques you’ve used and what you haven’t. Next time, instead of writing a requirements document, why not try another one of the methods suggested above? Consider the size of the problem you’re tacking and what might be the most appropriate method for slicing that problem.