Agile Documentation: Specification by Example
Like this article? We recommend
Like this article? We recommend
Like this article? We recommend
Agile proponents promote minimizing the work spent at the outset of a project ("up front," as they like to say). Instead, they recommend specifying features "just in time"—on a regular basis, the business presents a small and next-most-important batch of desired features. From this batch, the developers commit to what they can deliver within the next week or two.
In this incremental world, Agile teams rarely create detailed specification documents. Instead, Agile favors oral communication: The business and development team work together very closely, daily and continually discussing the precise details of what to build. This oral collaboration saves the significant effort of trying to pin down every last detail up front and then putting these details in writing. Recording information in writing doesn't necessarily make things better—developers too easily misinterpret written specifications if the team hasn't invested a lot of painstaking care in wording. However, oral conversations are quickly forgotten once the team has delivered the completed work. The business must not only convey details while developers are building the system; somehow these details must be captured for the sake of future understanding of the system.
Teams always do capture details, in one sense—if necessary, you can glean how a system works by analyzing the deployed system itself. But that analysis takes considerable effort, depending on the system's implementation. In order to sustain growth of a system, teams need a more efficient way to understand its precise behaviors.
The Agile way of capturing system behavior is by backing the stories—the features to be built—with detailed acceptance criteria. These acceptance criteria should be supported by a set of automated tests. If everyone is in agreement on the acceptance criteria, then teams know they can stop programming once all the associated tests pass.
Use Cases in Agile?
Ivar Jacobson devised use cases as a means of requirements analysis. He also said that use cases can generate value throughout the entire software development lifecycle: You can employ use cases to reconcile your design, to understand what to code during implementation, and to act as the basis for a test plan. If use cases are done well, you can even use them to help create user manuals and help guides. That last item is particularly compelling—use cases as the basis for documentation on the system's capabilities.
Agile teams don't typically employ use cases. However, teams can realize the spirit behind Jacobson's invention through the use of automated acceptance tests (ATs). When teams create ATs with readability in mind, they can document appropriate uses of the system. Automated ATs go one step beyond use cases: They're unambiguous. They either pass or they don't. If the test passes, the system behaves in the manner that the test specifies.
The caution is that automated acceptance tests are not a precise replacement for use cases. Automated ATs do fulfill the spirit of use cases (to express all the goals that can be accomplished with the system), but the granularity can be significantly different. One use case, complete with alternate and exception cases, might be supplanted with a "happy path" acceptance test plus a number of corresponding but separate alternate and exception tests. Or a use case might map to dozens of tests, with some tests verifying only small portions (business rules) of a larger goal.
It's costly to create and maintain system documentation, which too easily gets out of sync with the system. It's also costly to create and maintain automated acceptance tests. Combining the two efforts, by creating automated tests that act as documentation, creates tremendous potential for cost savings. It also produces a mechanism to ensure that documentation will stay up to date—tests don't get stale so easily!