Chapter 3 Living documentation |
35 |
consider this premise important for the future. I hope that the readers of this book will be able to get great results easier and faster because of looking at the process from this different perspective.
For example, understanding that living documentation is an important artifact instantly determines whether to put the acceptance tests in a version-control system. A focus on business-process documentation avoids overly technical speciications and keeps the speciications focused on what the system is supposed to do from a business perspective, not on test scripting. Cleaning up test code no longer requires a separate explanation. Enhancing the structure or clarity of tests is no longer something to put on the technical debt list: It’s part of the standard list of tasks for delivery. The law in delegating the work on acceptance tests to junior developers and testers suddenly becomes obvious. The fact that useful documentation has to be well organized should prevent teams from piling up thousands of incomprehensible tests in a single directory.
By considering the living documentation a separate artifact of the delivery process, teams can also avoid overinvesting in it. They can discuss up front how much time they want to spend building the living documentation system and avoid falling into the trap of gold-plating the tests at the expense of the primary product.
I suspect that keeping speciications too abstract might be a potential pitfall of the documentation model. I expect this model to work better for software systems that are built to automate complex business processes. User-interface centric projects where the complexity isn’t in the underlying processes might not beneit as much.
Remember
•There are several models of looking at Speciication by Example. Different models are useful for different purposes.
•Speciication by Example allows you to build up a good documentation system incrementally.
•Living documentation is an important artifact of the delivery process, as vital as code.
•Focusing on creating a business-process documentation system should help you avoid the most common long-term maintenance problems with speciications and tests.
4
Initiating the changes
Many ideas central to Speciication by Example have been around for decades. In the late 80s, Gerald Weinberg and Donald Gause wrote about communication problems with software requirements in Exploring Requirements:
Quality Before Design.1 The authors suggested that the best way to check for completeness and consistency of requirements is to design black-box tests against them— effectively suggesting the duality of speciications and tests in Speciication by Example. In 1986, the German army used what later became the V Model to describe ways to build acceptance tests before implementation for validation. Today, we use the same method but refer to acceptance tests as speciications with examples. Ward Cunningham applied the practices of illustrating using examples and automating validation without changing speciications on the WyCASH+ project in 1989.2
Unfortunately, these ideas didn’t catch on at the time. Long development phases made them impractical to execute. People spent months trying to write abstract requirements for projects that would last years. Detailing everything upfront with examples would delay that even longer.
Agile development changed the way the industry thinks about software delivery phases—and shortened these phases signiicantly. This made Speciication by Example feasible. Iteration and low-based projects can beneit greatly from Speciication by Example. With so little time to complete a delivery phase, we need to eliminate as much unnecessary work as possible. Common problems that require ixing are rework, duplicated tasks caused by miscommunication, time wasted working back from code in order to understand the system, and time spent repeatedly executing the same tests manually.
1Gerald M. Weinberg and Donald C. Gause, Exploring Requirements: Quality Before Design
(Dorset House Publishing Company, 1989).
2http://it.c2.com/wiki.cgi?FrameworkHistory
36