One of the exciting things I get to do as part of being a Product Manager at Atlasssian 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 maintaing the documentation.
Whatever floats your boat
- 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 vist 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:
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. Throughout the process of exploring the problem, we observed that our “not doing” or “out of scope” list kept growing. This helped our team stay focused on the most viable solution we could ship. In addition, because this feature was an improvement to another feature – our editor, with a large set of existing functionality, 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 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, smaller, 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. Instead of writing your next PRD 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. Have you deployed other techniques to communicate requirements in your teams? I’d love to hear what you may have done.
Coming up…
There are many scenarios where you will still need to put pen to paper and define the problem. So when you do what does this look like in an agile world? For the second post in this series, we will look at how we write requirements documentation in an agile team and reflect on the underlining principles which guide us across this tightrope.
Update: A complete guide to agile requirements can now be found on The Agile Coach, our no-nonsense agile tutorial site. See you there!
P.S We’re hiring! Has this post got you interested in what we do Product Management at Atlassian? Interested in joining our team? We’ve got plenty of open product positions right now. Why not join us on our quest to help teams build great software!