Documenting requirements is one of the key activities performed in requirements engineering. Even though projects using traditional development approaches naturally perform documentation, many practitioners in agile development projects avoid practicing the documentation of requirements because it is considered too much of an effort with too little gain. Why this is the case, and how requirements documentation can remain agile, is what we explore in this five-part blog series.
In the first part of this series, we investigated why requirements are documented at all. In part 2, we debunked the myth that no requirements documentation should take place in agile development settings. Knowing that the spiritual fathers of agile development did intend requirements to be documented, in part 3 we will now assess how documentation can play a constructive role in an agile setting, but first we need to understand what challenges requirements engineering faces.
Although agile approaches have brought improvements to many development situations, new challenges have also arisen. An extensive overview grouped about 50 problems encountered in agile settings into four categories [18], from which we will describe some example challenges that could be alleviated or resolved with good requirements documentation practices:
Communication and changing culture & mindset: Documented requirements are an important aspect in communication. They often serve as the basis for discussions and decisions, so they can help resolve problems such as communication bandwidth being too narrow.
Buy-in from management, customers, and team members: Documented requirements can be used as visible and convincing evidence of the quality of work and the planned steps. The documentation can also help to involve project members better, thereby boosting morale.
Managing day-to-day operational problems: The requirements documentation is the basis that helps to assure good requirements development and provides the information needed to perform requirements management operations such as tracking and visualizing project progress, making effort estimations, and assuring that the results from testing can be addressed before release.
Gaining experience and making it work: Experience and documented material to enable comparison are helpful for more reliable budgeting, reuse, and scaling to large projects.
Our industry experience shows that with regard to agile approaches, practitioners often face challenges related to the activity of documenting requirements, such as:
- Why do some things need to be documented, and what parts of existing documentation can be seen as requirements-relevant?
- How to contain the size of requirements documentation, avoid chaos, and promote clear communication?
- How to best assign responsibilities for creating / reviewing contents, and how can tools help structure this information?
- How is requirements management (changes, prioritization, releases / versioning) performed in agile settings; for example, how to deal with change requests efficiently and how to use tool support?
In agile settings, requirements engineering is approached in a different way. The role that comes closest to that of a requirements engineer is the Product Owner (PO). In settings without any real requirements documentation, this role is also considered a kind of “walking requirements document”, but if the PO is absent and there are no or only poor requirements stored in the Product Backlog, nobody in the team can really know the requirements. In such settings, this is one of the major causes of chaos in agile processes.
Agile settings often do not prescribe who is allowed to add and edit documented requirements (for example in the form of user stories) so as to assure quality. If prescribed templates are available at all, these are often not followed, and the PO typically does not spend their time reviewing and harmonizing them. This means that quality problems with the requirements, especially ambiguity and inconsistencies, are not resolved.
Another problem is that the documentation is too brief. Although this seems to reinforce the agile principle of requiring team members to communicate the details, in practice a lot of effort is needlessly put into clarifying or explaining the same requirement to several persons if they do not understand it, which conflicts with the goal of Agile to boost efficiency. The best solution in this case is indeed to document more information. However, this raises another pressing issue, which we will tackle in the third and final instalment of this trilogy: How to determine the appropriate documentation size to best treat requirements documents in your agile setting while still preventing a proliferation of documentation?
references
[18] Miller, G. J. (2013). Agile problems, challenges, & failures. Paper presented at PMI® Global Congress 2013—North America, New Orleans, LA. Newtown Square, PA: Project Management Institute.