The documentation of requirements is an important means within requirements engineering. In projects with few requirements changes over their runtime, good documentation can be achieved with relative ease. For agile projects, however, it is in their nature that their requirements as well as their compositions change continuously. The resulting need to adapt and update requirements in the documentation is often considered unnecessary additional work. How this perception came to be and how documentation can be dealt with in a way that boosts its advantages in Agile is the focus of this five-part series of blog articles.
In the first part of this series, we investigated why requirements are documented at all. Part 2 addressed how requirements documentation was never meant to be dropped from agile development but remains an integral part of the development approach. However, to make requirements engineering work in agile settings involves tackling particular challenges, which we discussed in part 3. In this fourth part, we assume that requirements are being documented, but one final hurdle still has to be overcome: preventing chaos resulting from a proliferation of documentation.
Documented requirements are a necessity for fostering communication, especially within the development team, but also with other stakeholders. They help practitioners to better understand the needs of the stakeholders. Furthermore, they are useful for getting early feedback in short feedback cycles and for adapting to changes in stakeholder needs. With optimal verbal communication, where the exchange is intensive and continuous, the requirements documentation could be less formalized, but distributed teams, language barriers, and time restrictions often impair direct verbal communication [6]. As a result, optimal communication should not simply be assumed.
With respect to the agile value of putting working software over comprehensive documentation, the most suitable amount and degree of detail of documented requirements should be determined for each particular project setting. This can be considered from a bottom-up or a top-down perspective.
- The bottom-up perspective considers what the minimum amount of documented information is. The communication within the team is a key aspect for deciding what should be documented and what should not. Information should only be documented if this information has a target audience, which in this case means a specific consumer for whom the information is documented [1], and if the use of documentation brings additional value [6]. By regarding and regularly obtaining feedback from a consumer within the project, many problems related to the necessity, understandability, and unambiguity of the requirements can already get resolved. However, some stakeholders from outside the project may also be an important audience that warrants a particular requirement to be documented. For example, legislative and standardization bodies may require certain requirements to be documented for legal purposes, to assure traceability, or to safeguard long-term maintenance.
- From the top-down perspective, heuristics are sought to set limits to the full scope of the requirements documentation. This concerns how to avoid ‘too much’ documentation, which in turn raises the question what is considered ‘too much’ or an overkill of documentation. There is no one-size-fits-all answer to this question. IREB suggests that the size of the project, the number of stakeholders involved, the presence of legal constraints, and the safety criticality of the project are all factors that determine the adequate degree of documentation [1]. This can indeed become quite an extensive set of backlogs in which containment of the requirements documentation by a PO becomes increasingly important.
How is your requirements documentation? Please contact us if you need expert help with introducing, improving, or revising your requirements documentation process!
[1] Adam, S., Doerr, J., Eisenbarth, M., Gross, A. (2009). Using Task-oriented Requirements Engineering in different domains: Experiences with applications in research and industry. In: Proceedings of the 17th IEEE International Requirements Engineering Conference, pp. 267–272.
[6] Baumann, L., Hruschka, P., Lauenroth, K., Meuten, M., Reis, Rogers, G. et al. (2017). IREB Certified Professional for Requirements Engineering – RE@Agile Primer: Syllabus and Study Guide (Version 1.0.2). Karlsruhe, Germany: International Requirements Engineering Board e.V. Available online: https://www.ireb.org/content/downloads/28-cpre-re-agile-primer-syllabus/ireb_cpre_re%40agileprimersyllabusandstudyguide_en_v1.0.2.pdf (last accessed 11 June 2019).