Standardizing Requirements Descriptions on Scrum Projects for Better Development and Testing Quality

The topic of requirement description formats is discussed quite often among business analysts. In this article, I share my experience with this topic on a recent project where applying one standardized format for all requirement descriptions improved the experience for testers and developers, increased team productivity, and created a more effective project flow.

Pitfalls Without Standard Requirements Descriptions

New Blood. When product owners manage requirements, they often don’t allocate enough time to properly describe them. The reasons for this are typically lack of time and pressure to start development as soon as possible. Or, the product owner may lack the necessary skills to document requirements in a suitable way. In any case, the experience of the team and their close knowledge of the application in question determine how well the development process will proceed. But what happens when new specialists come to the project? Appropriate documentation can seamlessly introduce new team members to the project and the product or service being developed. This is especially important on large, long-term projects where lack of documentation can lead to more serious challenges as the project runs its course.

Estimates. If requirements are described in a haphazard manner, without mutually understandable rules and clearly set standards, estimating those requirements becomes impossible when questions appear that cannot be answered. If something is missed and developers have already begun working, a bottleneck is created, time wasted and implementation delayed.

Scheduling. Without standardizing requirements descriptions, creating reliable project schedules that can be adhered to will be more difficult. When product owners skip detailed requirements documentation, the quality of development suffers due to more bugs and the time needed to fix them, making the implementation of a feature take more sprint time than projected.

A Scrum Project’s Before and After

The direct impact of standardizing requirements descriptions on development can be seen in the example of a large social media company that owns several popular websites used by millions. A rapidly developing Agile project, with high reaching market goals set by stakeholders, existing documentation was narrowed down to information that served users and ongoing development purposes. The stakeholders were not interested in investing in the creation and support of hundreds of pages of documentation, which would have made sense and is common practice for most Agile projects.

The client already had their own development team and many ambitious plans, but needed more resources to implement them. Therefore, additional support stepped in with a team of researchers, analysts and developers, and future plans to add a team of QA experts.

Once the new team was brought together, the product owner’s schedule opened up enabling them to focus more on business direction, strategy and negotiations with business owners, while the new project lead was able to begin preparing structured and complete requirements descriptions thorough enough for development and quality.

The team was distributed globally: part of development was in the U.S., located in different states; another part was in Minsk. The business owners and product owner resided in the U.S., and users were scattered across the U.S. time zones. Since frequent and effective communication between all team members was an essential part of the project, the time difference added yet another layer of complexity. ­­

Before Standardized Requirements Descriptions

Before implementation of standardized requirements descriptions, user stories were described without following any particular format: requirements were not detailed enough, scenarios were missing or too short, and overall, they were simply insufficient for developers. This led to a few negative consequences, including:

Estimation Difficulties. During grooming meetings, questions arose that until answered, didn’t allow for adequate time estimates.  

Questions and Gaps. During the development and testing stage, you may find some important aspects were not considered for feature implementation (e.g., missing scenarios, exception flows, etc.).

Time and Effort Wasted. At this point, the effectiveness of the whole team suffers: estimates for tasks were not met, as they did not cover implementing additional requirements; tasks may not be completed by the end of the sprint; and users were unsatisfied because of delays in the roll out of new features. Additionally, more time is spent explaining to stakeholders why there were missing requirements, and why the development team needed to repeat the implementation of features and testing tasks.

After Standardized Requirements Descriptions

To improve the situation, the development team began using a standard description approach with a "classic" requirement statement: 

In addition, acceptance scenarios were used based on the following template: 

At the start of the project, new developers on the team who were starting to learn the system were not helped by a short statement such as, "When approving an influencer in the queue, the system should show an alert in their dashboard."

As a result of introducing the above mentioned format, developers and QA engineers benefited from full descriptions with detailed steps and links to relevant pages. This significantly reduced the number of questions asked, and the idea of “quality” and its metrics became clear since it was documented in detail.

Of course, where needed, we accompanied user stories and acceptance scenarios with supporting artefacts. These included UI mockups to illustrate changes in UI, design specifications where the changes affected end-user interface, and multiple diagrams. In most cases, the diagrams were used to illustrate changes in process and show the entire team what needed to be changed globally for a system module as a result of implementing a range of user stories.

Project Example of a User Story Accompanied by the Main Acceptance Scenario:

*The scenario above became the primary one, chosen out of three existing scenarios for the user story that were created to ensure full coverage.

Benefits of Requirements Descriptions Unification

1. 360-Degree Clarity. When working on a full description based on a standard template, questions will come to light that may have otherwise been missed. The template guides push the product owner and the team to think of each step in the flow and ask more questions. These questions are clarified before the user story goes to estimations and development, saving time for the team since fewer issues are encountered later, during later and more critical project stages. Thus, all processes are more transparent and project budgets are spent more efficiently.
2. Full Coverage. There is a higher probability that all possible flows and alternative scenarios related to the requirements will be described fully and with relevant details, improving quality of development and simplified testing.
3. Better Performance. As a result of the first two benefits, the performance of the whole team increases as fewer bugs related to the user story implementation are reported by users and testers. Performance is also better because time on clarifications isn’t wasted, more tasks are completed on time and user stories are not blocked.
4. Documentation of Every Requirement, Process or Feature. When working on a large project with different modules being developed simultaneously, complicated functionality and tens of thousands of users with multiple user roles, multichannel communication makes it impossible for business analysts to memorize every project detail. With standardized requirements, they can simply search for every answer to every question asked that is included in the user story descriptions as a separate scenario or step in a scenario.
5. Better End Product. Adding unified descriptions in JIRA for each feature may not only help project newcomers, but also the overall understanding of the system itself as its inner workings are described and understood in full by all members.
6. Saving Time on Communication. Especially when it comes to outsourcing projects, with the time difference thrown into the mix, everyone benefits from the absence of gaps or bottlenecks in development.
7. Higher Development Quality. Overall quality of development is higher, because everyone understands requirements in the same way without ambiguity. Scheduling is also easier since estimates are simpler to make.
8. Easier Modifications to Requirements or Scenarios. If sufficient time is spent on writing detailed requirements, then making changes to them will be effortless. Investing in a business analyst who clarifies and describes requirements well will save time and money overall.

Standardization and Testing

With standardized requirements it is much easier for testers to understand the system, its features and modules. Testing becomes smoother, as acceptance scenarios cover all the functional flows in detail. As a result, there is more time to spend on testing rather than learning about the system. Testers can also contribute to the completeness of requirements descriptions by noting if an aspect of a feature was missed.

In addition, detailed descriptions narrow down information on a feature or module, so testers understand that if something is supposed to function as described in the requirements, it should work exactly as written. Misunderstandings and misinterpretations based on personal opinions or perspectives are eliminated.

Managing Ongoing Changes in Requirements

Without documentation on projects, keeping user stories in JIRA is a safety cushion for the future project business analysts, the development team and anyone else who joins the project. If any part of a process in the system needs to be changed, it is easier to do so thanks to the comprehensive keyword search capabilities in JIRA where you can find requirements in a particular scenario and see which scenarios to consider.  

Also, on this particular project, when implementing additional tests on the most important features, reliable and interested users were assigned as “watchers” for corresponding tasks in JIRA. They performed acceptance testing to find out if the feature was understandable, as well as completely and correctly implemented before its release. They would watch the task from the very beginning, so they could track what was happening with a requirement, check its description as soon as it was created, and let business analysts and product owners know if any updates were required. Having requirements described in the view of acceptance scenarios helped them make it clear for themselves what exactly they needed, and helped to ensure the description was not ambiguous.

Conclusion

There is a clear correlation between properly unifying the format of requirements descriptions and a project’s success. The iterative process is easier and every step in it adds value to the whole system with less bugs and delays. The team benefits from simpler scheduling, which leads to faster development and is especially crucial on large projects that may be lacking resources.

In the case of our project, business stakeholders benefitted from a healthier budget that was not wasted on fixing bugs, but was focused on implementing new features that worked as intended. The implementation of standardized requirements descriptions made the entire project run more smoothly, allowing the team to deliver new functionality modules and features quickly, while also meeting all expectations in full. This resulted in happy users and pleased stakeholders.

About the Author

Elena Belkovskaya graduated from Belarusian State University with a degree in economics. Before joining Itransition, she worked as an economist. At Itransition, she is a business analyst where she applies seven years of experience in IT using Waterfall and Agile methodologies. In her work, Elena effectively utilizes solid analytical skills in all phases of the enterprise project lifecycle, including requirements development and management, functional and training documentation, business analysis planning and estimation, onsite and remote communication on project requirements, and system design issues. She is passionate about advancing her skills through training courses and participation in leading industry conferences.