Software documentation as a guidebook

I agree that the problem is that when most people think 'documentation' for software projects, they think of comprehensive documentation - something that is not only very hard to do, but also almost always a bad idea.

I also agree with something that is implied in the article - that documentation should be of multiple types: including wiki and UML, but also unit and integration tests.

The part that I find interesting, is that the above results in three things: Be open to the fact that each documentation type might have diminishing returns, so as developers we should not be religious about just UML or just unit tests, but be make sure to have multiple types of documentation. Realize the obvious that that documentation should not get in the way from the project responding to customer needs (i.e. code base being agile), and therefore the documentation must be ideally as less as possible. And that finally, there needs to be a way to find the right type of documentation when you want it.

I think the last part is a field where there needs to be research. Getting it correct has been one reason why unit tests have worked so effectively. We need more people thinking about this part.

Does anyone think of Documentation as a feature? When documentation - which is typically not the most fun bit of a project - has to be fought for by the developers, to have any more than the most basic hand-wavy guide to what's going on can seem an unnecessary luxury...or so management may think!

But then do I make it a point to make sure my code IS well documented? Maybe another resolution for this year..!