Agile development and software requirements documentation

Agile development methods may have a different approach toward requirements documentation, but following agile doesn't preclude the need for good requirements documentation. Expert Karl E. Wiegers explains how to document requirements within the agile methodology.

Does agile development methodology (build small, get it confirmed at the earliest, rework if needed) cut down need for good requirements documentation before the actual work starts? Is it not needed because work is in smaller chunks?

Agile software development approaches do provide several techniques that, in appropriate situations, can allow teams to simplify their requirements documentation. But this is not the same as saying you don't need "good requirements documentation." You always need high-quality requirements that accurately convey the essential information to the various stakeholders. The central issue is the timing and the degree of detail in the requirements.

The incremental development approach acknowledges the reality that it is usually not possible to fully specify all of the product's requirements at the outset and then simply build it. However, you do need to know enough about the whole set of requirements at a high level so that the customers can prioritize them, so the development team knows what to work on in each increment. So an important idea is to specify and document requirements in layers of increasing detail at the right time. There's no point in specifying highly detailed requirements for a portion of the product that you won't implement for many months or perhaps ever.

Another agile tenet is close collaboration between the development team and customer representatives. This can reduce the detail needed in the requirements documentation, as the details can be filled in, refined, and adjusted at the right time. But there's a downside: Unless you document the information, you do not have a written record of the requirements that ultimately were implemented. This information gap can pose problems during maintenance, when reengineering a product in the future, when business rules change, and when new people replace members of the original development team. It's also an issue when attempting to trace designs and code and tests back to requirements to ensure that nothing was overlooked and everything built has a reason to exist.

Also common in the agile world is the notion of employing "user stories" in lieu of traditional requirements lists. I strongly endorse the emphasis on understanding how users will use the product to get their job done, rather than simply listing a bunch of product features that seem like a good idea. But developers don't implement user stories; they implement functionality, code that causes the system to exhibit specific behaviors under certain conditions. So a translation needs to take place from a high-abstraction user story to the functional requirements.

Such a translation typically is responsibility of a requirements (or business) analyst, who derives the functional requirements to implement from an understanding of the user story, scenario, or use case. If you ask each developer to perform this derivation mentally on the fly, others can't review the requirements to ensure the derivation was done properly and you can't ensure that all the requirements were ultimately implemented. You also need to test all of the requirements. Agile approaches often address this by writing user acceptance tests, sometimes in lieu of detailed software requirements specifications. Unfortunately, not all implemented functionality is visible to the user, and that functionality must be correctly implemented and verified as well.

Requirements gathering resources:
How agile development affects role of business analyst

Software requirements specification and the IEEE standard

How to document system, software requirements

As with so many decisions on software projects, it boils down to a question of risk. You need to balance the risks arise from not writing detailed requirements against the cost savings. When developers and customers are working closely together in a small team, this risk is lower than if development will be outsourced or if people are collaborating in multiple development locations and need the shared group memory that written requirements can provide. But you still need to specify the requirements for each chunk of work, however small. And you always need "good requirements." How elaborate those requirements need to be is up to you.

Dig Deeper on Topics Archive