There are different veiwpoints to the topic as there are big differences in the circumstances of each project of each of us.

My task is usually more complicated than what Ian described, the clients are far less knowledgeable and far more demanding then usually. The v0.1 cannot be a mockup but it has to be the full application; however, there are substantial changes down to the skeleton even in v3.2, as the client finds out what he wants finally. And, it has to fulfill various contradictory requirements of several involved parties...

So there is no universal approach to documentation as there is no universal approach to electronic design either. This is not to say both of them are necessarily ad-hoc. I believe there are typical tasks which are best solved using standard methods, but if all problems would have predetermined solution, the programming would be no more fun and I would be looking for some other job - nuclear physics, molecular biology, neural surgery, anything else similarly trivial :-)))

But there might be some cues or general guidelines of course. A very good approach is what Erik mentions: document the internals of the program in the comments, document the interfaces in a strictly technical manner, do the user manual as a skeleton and leave it to anybody to blow it up - if the user wants a 300-pages manual with infinitezimally small informational density as the common software manuals today are, let him have it; the smart user could have the skeleton document.

The best documentation is written in such way, that you ask yourself all the time, whether you would understand it if you would be the user - but this is as hard to achieve as hard is it is to teach well (in fact, both are essentially the same proces).

Jan Waclawek