should we really encourage people to document LESS?

I found a link to this essay on Agile Documentation on Dr. Dobb's.

http://www.agilemodeling.com/essays/agileDocumentation.htm

As I read through the critical points, I found ideas that resonated with me as well as ideas I strongly disagreed with. I agree that documentation is great for organizational memory. When you have to support what you wrote (or what someone else wrote), you love that documentation. And as the article points out, documentation is also a great way to think something through. Overall, I think the author's heart is in the right place and with the best developers in the world, all this may be true. But like libertarianism, you can't assume that everyone is a good citizen. Take away all the environmental regulations and you betcha you'll have a neighbor dumping toxic sludge into your shared stream.

1. The Fundamental Issue is Communication, not documentation.
So true, but the documentation is your CYA when the other people claim you didn't say what you said.
10. Comprehensive documentation does not ensure project success, in fact, it increases your chances for failure.
I'd like to see the stats on that. Documentation alone is not a golden bullet, but I'd wager more projects fail due to lack of documentation than because of it.


The general point of this article argues against documentation, something I really believe in. I cannot believe the agile model is just so good that you don't need to document. What I see over and over "if you follow AM practices, you will not need so much documentation because you will produce code so much faster and of better quality." To me, it sounds like one of those reticent developers who just wants to code and not be bothered with anything else. I find this type really difficult to work with both as a fellow developer and as a project manager, and especially as a customer.

So, how do I respond to some of these "questionable reasons for creating documentation". I'll take just a single one of them...

The requester wants to be seen to be in control. People will request documents, such as specifications and detailed architecture documents that they can sign off on and say “yes, go ahead and build us one of these.” Whenever I find myself in this situation I ask the individual(s) requesting the documents if they also want to be seen as responsible for the project's failure because the development team was too busy focusing on needless documentation and not on building software. I’ll then suggest that instead of requesting documentation they should instead request access to the software itself, even if it is just an internal release of the software, so they can provide constructive feedback about it. They can still be seen to be an active participant in the project and can do so in a productive manner.

And this protects the developer(s) or the consultants more than it protects the customer! In consulting, we called it a Statement of Work and it was our bible. Access to the software itself is great - if you have the software built already. But how much time do you want to waste building software if you haven't yet documented what the customer asked for?