Most interesting quote so far in a book I picked up at JavaOne: “System Documentation is a Business Decision, Not a Technical One” – Agile Modeling, Scott Ambler. The gist of his statement is that writing (and then verifying and maintaining that documentation) takes time and resources that would otherwise be committed to other areas on a project. Documentation is one way of spending development resources, one which may help reduce certains kinds of project risks.

So, before you send me off to write another detailed design document or in-depth maintenance plan, think about what functionality you’re now willing to give up. In practice, what happens is that we squeeze the documentation in, churning out pages fit mostly as evidence that we’ve “done the documentation”, since payment milestones for contracts are often tied to delivery of those documents. But the net value to the customer for that document is negative, since the document doesn’t provide enough value within it to be worth the time reading it, much less the time writing and editing it.

Enjoying reading Mr. Ambler’s book (though he would have benefitted from a better editor). Enjoyed hearing him in person at JavaOne, as well. Always interesting to match a face to a name, and to hear what someone says when they’re a bit more unscripted than in a book. His Australian outback hat was a nice touch.