2009-03-02
Critical Points about Agile Documentation
Scott Ambler’s discussion of agile documentation is enlightening in many respects. I would encourage development teams to add agile documentation practices to their toolbox. However, I’d like to suggest a few places where these tools could be sharper, at least from the perspective of documentation to deliver as part of the system, as opposed to documentation generated during the development process. Let’s take a close look at Ambler’s critical points.
- The fundamental issue is communication, not documentation.
Right on. No need to document the obvious. And, with good design and user interface, what stakeholders need should, for the most part, be obvious. - Agilists write documentation if that’s the best way to achieve the relevant goals, but there often proves to be better ways to achieve those goals than writing static documentation.
I understand these better ways to include good system design, good user interface, and other ways of communicating with stakeholders, such as live training and support. - Document stable things, not speculative things.
This point hits on timing of documentation activities and counters the tendency in some quarters to overdocument the development process itself. - Take an evolutionary approach to documentation development, seeking and then acting on feedback on
a regular basis.
Right on. Documentation is not written in stone. We could even extend this idea to include support for interactive documentation, some of which is contributed by stakeholders themselves during transition or production phases, as the need arises. - Prefer executable work products such as customer tests and developer tests over static work products such as
plain old documentation (POD).
Again, the focus here is to counter the overdocumentation of the development process itself. We could, however, extend this idea to the creation of executable documentation systems that include both dynamic information from the run time system and interactive documentation creation features. One of the reasons why documentation is often less than useful is that it is not integrated with the run time system that stakeholders need to interact with. - You should understand the total cost of ownership (TCO) for a document, and someone must explicitly choose
to make that investment.
Again, this point counters any tendency to simply follow prescriptions as to what documentation is needed rather than to agilely determine the specific needs for your project. - Well-written documentation supports organizational memory effectively, but is a poor way to communicate during a project.
Right on. - Documentation should be concise: overviews/roadmaps are generally preferred over detailed documentation.
Right on, in keeping with the principle to assume simplicity. - With high quality source code and a test suite to back it up you need a lot less system documentation.
Right on. - Travel as light as you possibly can.
Right on. - Documentation should be just barely good enough.
Right on. This should nip in the bud any tendency of technical writers to make finely crafted topics an end in themselves. - Comprehensive documentation does not ensure project success, in fact, it increases your chance of failure.
This point has no bearing on stakeholder documentation delivered as part of the system. - Models are not necessarily documents, and documents are not necessarily models.
Nor does this point. - Documentation is as much a part of the system as the source code.
Here is a point that I would like to see prominently at the top of the list.
One of the necessary implications of this point is that you need to develop documentation for stakeholders with all of the skill, care, and agility that you devote to the rest of the development process. You should also integrate documentation into the run time system as much as possible, rather than deliver documentation that is both physically distant (in separate files or binders) and semantically isolated (dealing with the generic system, not the one that is actually deployed at my site, with its custom settings).
Thus, some of the specialties that you need represented on your development team are document engineering, content management, editorial practices, and publication. Contrary to popular belief, documentation is not something just any monkey can do, especially when your system presents the need for localization.
For a large-scale ecosystem of application development, this point also implies definite input from the environment, enterprise architecture, and software improvement disciplines in the enterprise unified process. Content needs from project to project may vary considerably, but the basic set of channels (online help, support wiki, &c) and components (topics, glossaries, &c) for documentation remain pretty constant. - Your team’s primary goal is to develop software, its secondary goal is to enable your next effort.
Another point whose primary focus is documentation of the development process, not documentation deliverable as part of the system. - The benefit of having documentation must be greater than the cost of creating and maintaining it.
Spot on. - Developers rarely trust the documentation, particularly detailed documentation because it’s usually out of
sync with the code.
Another point whose primary focus is documentation of the development process, not documentation deliverable as part of the system. - Each system has its own unique documentation needs, one size does not fit all. Right again.
- Ask whether you NEED the documentation, not whether you want it.
If the you here is the development team, then we need to extend this to include the stakeholders, who also might request documentation just because they think they need it, without demonstrating that need. At the end of the day, though… - The investment in system documentation is a business decision, not a technical one.
The customer gets what the customer pays for. - Create documentation only when you need it at the appropriate point in the lifecycle.
Another point whose primary focus is documentation of the development process, not documentation deliverable as part of the system. - Update documentation only when it hurts.
Good point.
Rich Analysis 