Creating a lean, mean
requirements machine

Nobody likes writing bloated, ultra-detailed requirements. Turns out nobody likes using them, either.

 

Agile requirements are a product owner's best friend. Product owners who don't use agile requirements get caught up with spec'ing out every detail to deliver the right software (then cross their fingers hoping they've spec'ed out the right things). Agile requirements, on the other hand, depend on a shared understanding of the customer that is shared between the product owner, designer, and the development team. That shared understanding and empathy for the target customer unlocks hidden bandwidth for product owners. They can focus on higher-level requirements and leave implementation details to the development team, who is fully equipped to do so – again, because of that shared understanding. (Boom.)

If you're excited by the idea of a shared understanding, but haven't a clue how to create it, try some of these tips:

  • When doing customer interviews, include a member of the design and development teams so they can hear from a customer directly instead of relying on the product owner's notes. It will also give them the chance to probe deeper while the topic is fresh in the customer's mind.
  • Make developing and using customer personas a team effort. Each team member has unique perspectives and insights, and needs to understand how the personas influences product development.
  • Make issue triage and backlog grooming a team sport as well. These are great opportunities to make sure everyone is on the same page, and understand why the product owner has prioritized work the way they have.

When the team and product owner share the same mindset, you don't need ultra-detailed requirements.

Anti-patterns to watch for

  • The entire project is already spec'd out in great detail before any engineering work begins
  • Thorough review and iron-clad sign-off from all teams are required before work even starts
  • Designers and developers don't know when requirements have been updated
  • Requirements are never updated in the first place (because everyone signed off on them, remember?)
  • The product owner writes requirements without the participation of the team 

Ok: you’ve discussed a set of user stories with your engineer and designer. Gone back and forth, had a few whiteboard sessions, and concluded there are a few more dimensions you need to consider for this feature that you are working on. You need to flesh out some assumptions you’re making, think deeper about how this fits in the overall scheme of things and keep track of all the open questions you need to answer. What next?

Keeping requirements lean with a one-page dashboard

When writing requirements, it's helpful to use a consistent template across the team so everyone can follow along and give feedback. At Atlassian, we use Confluence to create product requirements with the Product Requirements Blueprint. We've found that these 8 sections give "just enough" context to understand a project's requirements:

1. Define project specifics
We recommend including high level direction at the top of the page. Include:

  • Participants: Who is involved? Include the product owner, team, stakeholders
  • Status: What's the current state of the program? On target, at risk, delayed, deferred, etc.
  • Target release: When is it projected to ship?

2. Team goals and business objectives
Get straight to the point. Inform, but don't bore.

3. Background and strategic fit
Why are we doing this? How does this fit into the overall company objectives?

4. Assumptions
List the technical, business, or user assumptions you might be making.

5. User Stories
List or link to the user stories involved. Also link to customer interviews, and inclused screenshots of what you've seen. Provide enough detail to make a complete story, and include success metrics.

6. User interaction and design
After the team fleshes out the solution for each user story, link design explorations and wireframes to the page.

7. Questions
As the team understands the problems to solve, they often have questions. Create a table of "things we need to decide or research" to track these items.

8. What we're not doing
Keep the team focused on the work at hand by clearly calling out what you're not doing. Flag things that are out of scope at the moment, but might be looked at later. 

ProTip: The agile manifesto reminds us that we can be flexible with how we create requirements. Some teams do user story mapping exercises to identify problems and solutions. Sometimes the full product triad (product owner, developer, and designer) visits a customer and then brainstorms solutions to a particular problem the they mentioned.

No matter how requirements are born, it's important that the team considers them to be one of many ways they can define and communicate customer problems. See our section on agile design to learn how product owners can use Keynote and Powerpoint to mock up real experiences as requirements. 

But why?

If you are to take away anything from this blog, understand the “why” – the not “what” – because the “why” will help you explore what is best for your team. Here are the benefits and challenges we’ve observed with the one-page dashboard approach:

1. One page, one source, one problem
Keeping it simple. The requirements page becomes the “landing page” for everything related to the set of problems within a particular epic. Having something that is the central go-to location saves your team members time in accessing this information and gives them a concise view.

2. Extra agility
One of the awesome things about using a simple page to collaborate (verses a dedicated requirements management tool) is that you can be agile about your documentation! You don’t have to follow the same format every time – do what you need, when you need it, and be agile about it. Chop and change as needed.

3. Just enough context and detail
We often forget how powerful a simple link can be. We embed a lot of links within our requirements pages. It helps abstract out the complexity and progressively disclose the information to the reader as needed. Linking detailed resources my included such things as:

  • Customer interviews for background, validation or further context for the feature
  • Pages or blogs where similar ideas were proposed
  • Previous discussion or technical documentation and diagrams
  • Videos of product demos or other related content from external sources

4. Living stories
I see a lot of customers do this as well. Once the stories have been roughly thought out and entered as issues in JIRA, we link to them in our page (which, conveniently, creates a link from the issues back to the page as well). The two-way syncing between Confluence and JIRA means we automatically get to see each issue's current status right from the requirements page.

5. Collective wisdom
Capturing requirements Confluence (or whatever intranet you're using) makes it easy for other people in different teams to contribute and make suggestions. I’ve been amazed at the number of times someone from another team jumped into the conversation with a comment providing great feedback, suggestions, or lessons learned from similar projects. It helps a large organization feel like a small team.

6. Engaging "extras"
Diagrams made with tools like Visio, Gliffy, or Balsamiq better communicate the problems to your team. You can also embed external images, videos, and dynamic content.

7. Collaboration!
The most important aspect of all this is getting everyone involved. Never write a requirements document by yourself – you should always have a developer with you and write it together. Share the page with your team and get feedback. Comment, ask questions, encourage others to contribute with thoughts and ideas. This is especially important for distributed teams who don't often get a chance to discuss projects in person.

Challenges

With every approach there are down-sides. Here there are two main challenges we’ve experienced and observed from customers as well:

1. Documentation can go stale
What happens when you implement a story and get feedback and then modify the solution? Does someone go back and update the requirements page with the final implementation? This is a challenge with any type of documentation, and it’s always worth questioning whether such trade-offs are worthwhile. Talk to your team about what you would do in a scenario like this.

2. Lack of participation
“What can I do to encourage people to comment?”, “How can I encourage people to write more specs and stories on our intranet?”. This is a tough nut to crack, and it comes down to various wiki adoption techniques in your organization. There are plenty of resources to help you here. There may be deeper cultural issues at play here, too.

Now get to work!

When requirements are nimble, the product owner has more time to understand and keep pace with the market. And keeping them informative-but-brief empowers the development team to use whatever implementation fits their architecture and technology stack best.

Once a project's requirements are reasonably well-baked, we recommend linking the user stories in section 5 above to their corresponding stories in the development team's issue tracker. This makes the development process more transparent: it's easy to see the status of each piece of work, which makes for more informed decisions from the product owner, as well as downstream teams like marketing and support.

ProTip: Don't track the user stories that come from project requirements in one system and defects in another. Managing work across two systems is needlessly challenging and just wastes time. 

Remember, be agile in your evolution of requirements for a project. It's okay to change user stories as the team builds, ships, and gets feedback. Always maintain a high quality bar and a healthy engineering culture – even if it means shipping fewer features