Documenting requirements is a key activity in requirements engineering. However, despite the ubiquitous role of requirements documents, in agile settings the term “documentation” has a rather negative connotation. Poor documentation practice is often the result of an aversion to documenting, while the resulting problems of poor documentation further strengthen the belief that requirements documentation is detrimental to agile development. In this five-part blog series, we explore how requirements documentation can remain agile while preventing it from being a cause of chaos.
In part 1, we explored why requirements are documented at all. In part 2, we will now analyze why some argue against documentation in agile settings, in an attempt to set some misconceptions straight. The basis of agile development is a description of four values, which emphasizes a particular aspect of software development over another:
Individuals and interactions over processes and tools
Working software over comprehensive documentation
Customer collaboration over contract negotiation
Responding to change over following a plan
Especially the second value is often misinterpreted, by being read as though it were saying, “Working software instead of comprehensive documentation”, and people arguing that in agile, there is no documentation, or only scarcely. This is a fallacy, because this is not what the word “over” implies.
Imagine that it were true that the word “over” in these four values implied “instead of”. An agile team would then be a group of interacting individuals who do not follow any process or use any tools; they would not even have regularly scheduled meetings but would communicate spontaneously. They would collaborate with customers without any legal basis, and since they would be devoid of any plan, they would be clueless and wildly respond to any change that occurs. It would be a miraculous achievement if any working software came out of such anarchy at all.
Obviously, “instead of” is not what is meant in these four values of agile development. Rather, they indicate that when a choice needs to be made between one and the other, there is a clear preference. And even though these aspects are inferior to the other ones, it does not mean that they are unimportant.
In practice, it can be seen that the use of processes and tools is common in agile development, contract negotiations are important for many settings, and typically a clear plan is followed. What the values prescribe, however, is that each of these aspects should be dropped if a need arises from its more highly valued counterpart. This means that processes and tools must never prescribe how individuals work and interact; that contract negotiations do not govern or dominate the collaboration with the customer; and that the plan typically followed is instantly dropped if a quick response to change is needed.
Similarly, documentation should exist in agile settings, and needs to be as comprehensive as is ‘ideal’; no more and no less. What drives this ideal situation is that at the end of the day, the software should work well. This means that this (comprehensive) documentation is primarily concerned with ensuring that all of a system’s features are prescribed and can be implemented, with all of their functional facets and their qualities being properly met.
It is no coincidence that “working software” and “comprehensive documentation” are placed within the same agile value. They are closely linked to one another. Ultimately, the documentation contributes to and safeguards a system’s long-term success. Agile approaches were never conceived to have no documentation, and this is one of the most persistent misunderstandings in Agile. We are aware, though, that agile development settings face particular challenges with respect to documenting requirements. We will discuss typical challenges and constructive solutions in the next part of this series.