The Up-To-Dateness Problem

The other primary complaint about creating documentation other than source code is that, unless the docs are maintained alongside the source, they'll quickly go out of date; that reading documentation that's obsolete is worse than reading no documentation; and that effort that doesn't go into working code is effort wasted.

I'll address the second point first. The point of producing any form of developer documentation is to make it easier for developers to work with the software. Therefore, the cost of creating the documentation should really be weighed against the opportunity cost of not producing it. If the effort saved by letting developers get straight on with their work is greater than the time spent creating and maintaining the documentation, then it's worth doing. Conversely, if the trade-off doesn't work out, you need to decide whether to give up on that form of documentation for something more valuable or find a quicker way...