Earlier this week when I reviewed the dotProject Book – other than the massive amount of flak I've taken – I seemed to have touched the Third Rail of Software Development: Documentation. Let's be honest… developers don't like writing documentation, it's often out of date as its being written, and it has the tendancy to be wrong more often than not. So what do we do to combat this?
If you listen to the Agile types, you may reach the conclusion that documentation is unnecessary… well, not quite. When they talk about documentation, they couple it with rigorous refactoring to improve clarity, eliminate duplication, and generally get rid of "code smells". Unfortunately, this is entirely focused on the developer and/or maintainer of the code. While this is a fundamental consideration, it leaves out the fact that successful software has to have users and not all users will have been involved in the requirements/testing/etc processes.
If you listen to the Big Design Up Front types – yes, that's in Wikipedia too – you may believe that all the documentation is written at the beginning of the effort and combined with pretty drawings and screenshots as you go along. In some cases
If you have the marketing budget and multi-year release cycle of some companies, this whole effort becomes a bit trivial. You probably have a huge documentation group that handles getting new screenshots, comparing text against reality, and generally trying to make your users' lives easier…
So how can everyone else approach software documentation? In many cases, you can simply embed what documentation there is directly in the application via help files or whatever but any documentation will lag the code… it gets worse in Open Source Projects. Quite often the documentation can lag a release by weeks or months if it happens at all. The only exception to this rule are the output of the various documentation tools… but again, this is normally for developers, not for end users.
Is the state of things really as bad as it appears? How do you deal with documentation on your projects?