Comprehensive Documentation - Bad Assumptions

Agile is easy to dismiss. Many people hear something that doesn't sound right, something that sounds different than what they are accustomed to, and they develop misconceptions. They share their misconceptions with others. They dismiss agile without any more thought. A common misconception concerns documentation.

This came across my inbox recently:

I spoke to …, and he doesn’t have a requirement for Agile. He is familiar with the methodology, and his concern is comprehensive documentation. He believes that is a critical part of development that becomes less critical with the Agile methodology.  If his assumptions are incorrect, please let me know.

Are his assumptions incorrect? There are likely a lot of assumptions in that short statement:

• "Comprehensive documentation is a critical part of development." That may be true for his project. But it is not true for many projects. If he assumes that comprehensive documentation is too critical to do without on any project, his assumption is incorrect.
• "Comprehensive documentation becomes less critical with the Agile methodology." Often this is true. But that's a good thing. So, he's probably concerned about this…
• If he assumes you can't write comprehensive documentation on agile projects, his assumption is incorrect.
  You can write all the documentation you want.

Agile simply warns against using documentation as a measure of progress. Instead, agile favors working software as a measure of progress. If comprehensive documentation helps you get to working software, or adds value after the software is written, then create comprehensive documentation. If you have a regulatory environment you can't get around, then meet your regulatory requirements, but be creative and try to find an automated approach to generating it. If we're talking end user documentation and you can't make your application usable without end-user documentation, then write end-user documentation. If we're talking about installation instructions, agile favors automation, but if you can't automate and can't make it easy, then document it. If you have published APIs, create them with great care, provide great documentation and treat them as contracts.

If we're talking about requirements specifications, agile prefers requirements documentation in the form of user stories, constant collaboration between the givers of the requirements and the implementers of the requirements, and automated story tests. If you aren't there yet, if you don't know how to do that yet, then keep writing requirements documents for now, and strive for continuous learning and continuous improvement.

If we're talking about comprehensive technical documentation of the implementation, agile favors the software craftsmanship approach of refactoring towards small methods with very clear and descriptive method, variable, and class names. This leads to readable and self-documenting code. Agile also favors high code coverage through automated unit tests, which documents how to use the implementation and the intent of it.

Every instance of agile is unique. Each adoption of agile must be tailored for the context in which it will live -- the organization.

Usually, however, comprehensive documentation is waste. If the documentation doesn't match the source code, the documentation is wrong. Documentation is almost always wrong. Using misleading documentation is wasteful. Maintaining documentation is expensive and it rarely achieves a defect free state. More waste.

At the very least, this person shouldn't throw the baby out with the bath water. A lot of value remains in agile even if he disagrees with its warnings about documentation. I'm not saying that agile is suitable in his environment -- it in fact might not be. He may have no change or uncertainty in his environment. He may have a very repeatable and predictable situation, ideally suited for a plan driven approach.


In any event, this person is most assuredly concerned about how something will be handled, be it support (handled by pair-programming and a coded test suite) or design (handled by design-all-the-time, pair-programming, test suite, refactoring) or coordination (handled by collaborative space, published and documented APIs as contracts), or etc... I could assuage his fears if I new what was underlying them. That would require a face to face conversation. I'd welcome that opportunity. With him, or with any of you, my readers, or with any of your colleagues. My email address and phone number are noted at the top of my blog. Contact me at any time.