In an earlier blog, Death By a Thousand Cuts, we discussed the problems associated with using an unstructured approach for documenting product requirements and design. Unfortunately a lot of Agile teams are still following these unstructured approaches using Word and Excel documents for capturing requirements and design information. In our experience, using visual, structured and collaborative tools allow your business teams and product managers to lead the product features requirements definition, helping your products be better aligned with market and customer needs. You can define product feature requirements visually, instead of writing documents, allowing your teams to focus on delivering more working software. What are the tools and the fruits of this structured collaborative effort? In this blog, we will explore some best practices for documenting agile requirements.
Product requirements are the common language between business and engineering. Product requirements play a vital role also because they are the first step in the product development process – where value creation is highest. Any imperfections in the product requirements get amplified as they travel down the process making it costlier to handle these issues further downstream. There is a need and desire to invest in the upstream requirements and design processes because of these considerations.
Product Requirements Documents (PRD) were originally created when detailed product requirements were necessary before a project or production iteration. This became incompatible with the foundational tenets of the Agile Methodology that dictate requirements develop and evolve on the fly during each Sprint. A primary driver for this philosophy is that the entire set of requirements cannot be known ahead of time, as users often cannot describe what they need or want until they see it. The Agile manifesto believes in keeping documentation to a minimum. In Agile projects, documentation evolves over time and stakeholders strive to keep documentation as light as possible.
This conundrum can be resolved by having a fluid PRD that gets updated during each Sprint. However, this fluidity requires that the PRD be synchronized, shared and invited for collaboration such that team members can rapidly see evolving requirements and identify any issues that the evolving requirements could pose on the current Sprint and future Sprints. Indeed, the notion of a traditional PRD as a formal document has been slowly fading away with the advent of Agile. A centralized, dynamic and visually managed ‘System of Record’ for product requirements is becoming the preferred tool for managing this fluidity.
The key components of the Agile PRD should address the following areas in a lightweight yet thorough manner, while emphasizing flexibility and collaboration.
Business Goals
The business goals and objectives serve as the project context, showing the development team why they are building and what they are building. Unifying topics for good goal development include the purpose of this project, the product vision (the overarching goal you are aiming for, and the reason for creating the product), the problems that it will solve, and how it will streamline or improve the current process or facilitate a new process for your customers.
Epics and User Stories
A user story is a central tool used to capture a description of a software feature from an end-user perspective. The user story describes the type of user, what they want and why. A user story helps to create a simplified description of a requirement. User stories are generally narrative texts that describe an interaction of the user and the system, focusing on the value a user gains from the system.
In Agile parlance, a good user story adheres to the “INVEST” attributes:
Independent – Minimizing dependencies makes it easier to plan
Negotiable – Details revised or added via collaboration
Valuable – Provides value to the customer
Estimatable – A feature that is too large or too vague is not estimatable
Small – Can be done in generally less than a week by the project team
Testable – The user story has well defined acceptance criteria
An Epic is a series of user stories that are related in defining a product feature. An Epic is a feature described from start to finish, broken down into its constituent user stories. It’s a way of organizing your user stories in logical groupings – typically tied together by a single end user feature.
There is however a tendency in Agile teams to minimize the extent of details in the user stories. Keeping the description of the details of a user story to a few sentences runs the risk of leaving too much for imagination and interpretation. This leads to costly re-work in subsequent sprints. Indeed, Agile teams ought to strike the right balance of detail and lightweight documentation with some basic tools and techniques.
Business Process Workflows
Workflow is the definition, execution and automation of business processes where tasks and relevant information are passed from one participant to another for action, according to a set of procedural rules. For the PRD, workflows include a sequence of user actions and associated business rules. Workflows generally include a process flow diagram and pictures of the UI screens involved. Error states and view changes based on role are documented at this point. Business Rules are a great way of documenting these error conditions as well as any underlying business logic.
Workflows are developed to coordinate tasks between people and synchronize data between systems, with the ultimate goal of optimizing the efficiency and responsiveness of the feature. Summarizing the anticipated business process workflow for the user story will promote the flow of employee tasks and activities, reducing the time the process took to complete as well as potential errors caused by human interaction.
Agile Requirements Details
This section should include the details of the feature, including the UI screen(s) and every field, label, validation, message, and action. This is essentially the functional specification of the details of the screen(s) involved. This step can be accomplished more effectively with concise wireframes rather than using textual descriptions or even images mocked up using basic tools such as Paint. As they say, a picture is worth a thousand words. Pictures and visual diagrams tend to remove ambiguity that can creep in from purely textual descriptions of requirements. In some situations, you need to capture very fine grained requirements associated with the UI screens, for example – field level security that details what user profiles can see and edit the UI fields. Having this level of detail adds a burden on the team, but also eliminates the potential for undesirable surprises down the road.
While most of the product requirements document defines how the software will function, there is often a need to define the non-functional requirements as well. These include requirements that may be important to the business, but are not about how the software itself functions. Examples include where the product will be hosted, security requirements, performance and scalability requirements, and any browser-specific requirements to name a few. These non-functional requirements have a tendency to produce a nasty surprise when you least expect it – closer to the product release timeline. Having a good handle on these early in the process can be immensely valuable and helps lower delivery risk.
Integration Requirements
Integration related requirements including anticipated connections with outside applications (e.g. payment processing) also are an integral element of the requirements details that need to be holistically addressed instead of a siloed approach. A sufficient level of depth needs to be achieved with regards to the details, such as including the data fields, integration patterns and business rules associated with interfaces. Often times, due to the technical nature of these details, the business teams disengage from this process – something that needs to be avoided. Your application integration points are as much an enterprise IT asset, as are the applications themselves. They are a key part of the equation that gives your business a competitive advantage.
User Acceptance Test Criteria
User acceptance testing (UAT) is the process that obtains confirmation that a feature meets mutually agreed-upon requirements. The UAT acts as a verification of the required business function and proper functioning of the feature, emulating real-world usage conditions on behalf of customers. An important outcome of the PRD is a set of criteria to be met before the user story can be closed. Before the Sprint begins, the PRD should describe the customer acceptance criteria as clearly as possible. Identifying acceptance criteria and a general framework for UAT for a user story during the requirements development phase enables more clear thinking what UAT tasks are needed to validate the feature(s) envisioned in the particular User Story of the feature.
Closing Thoughts
The notion of managing requirements using formal documents is evolving given our adoption of Agile practices. A good product requirements document will save both time and money throughout the life of a project. Agile requirements documentation should evolve and stakeholders should collaborate to keep documentation as light as possible, while providing the necessary information to design and complete a Sprint. This fluidity requires that the PRD be synchronized, shared and invited for collaboration. Finally, the requirements development process and the PRD should be regularly and formally reassessed to find areas of improvement. Treat your product requirements development process as you would treat your overall product development: build, measure, learn, and repeat.
What challenges have you faced in your Agile transformation journey, pertaining to Software Requirements? What has been your experience in managing Software Requirements in an Agile environment? We would love to hear your experiences and lessons learned in the comments section below.