Whether you love or hate Agile development methodologies, you need to read a whitepaper by Jim Highsmith entitled “Objections to Agile Development”.
Jim addresses objections that stakeholders make to Agile development. The categories are:
- Buyer reality
- Bad or no design
- Doesn’t work with our business partners
- No documentation
For each of the objections above, Jim does a fine job of explaining why these objections are unfounded. I’ll address the “no documentation” bullet from my own experience, but please read the whitepaper as well. I’ve battled many objections to Agile at a previous job.
If you’ve ever created design documentation (UML diagram, etc), you know that it is out of date as soon as it’s printed. Developers make design decisions throughout the coding process (Coding is design, and Jack Reeves take). It takes a lot of time to keep a design document current, and it just never happens. Design documents get created; they are shown to management; they look pretty, and they are plain wrong. They never describe the actual structure of the system. A manager may like them, but they are looking at a picture, not the actual system. The actual system ends up structured in a different way, but the manager doesn’t know. The manager isn’t reading the code. The manager goes on in ignorant bliss with a picture of something that doesn’t exist. Arguements can be made about how the process is “supposed” to work, but there’s also reality.
The time for documentation is when the project is finished, and it’s time for it to be mothballed. This is when documentation should be created for maintainers who may come later. The system has stopped changing and is actually in a state where it can be documented. This is maintenance documentation.
Throughout the project, the code and tests should be the documentation for the code. This is the only thing that is guaranteed to remain current. Developers should be able to look at the structure of the system in the IDE and understand it. The whole solution layout also has documentation qualities.
I’d be interested in finding out if anyone has created a design document before the system was created where the document actually stayed current and meaningful.