Many moons ago on perlmonks I asked: How to write documentation?. I got some answers but overall I was not satisfied with the responses.
This week someone else has asked essentially the same question: creating documentation.
What I can say is that in the time between the two I've worked on a number of projects and you can tell when the documentation is correct.
In one project I created POD in the module and applications based around it and there were also comments in both the Perl and Shell scripts. I also wrote detailed documentation (in plain text) about every aspect of the project, so that it should be possible to reimplement it without me being there. I even wrote man pages for some of the shell installation steps. We tested the documentation when we moved the project into "QA" refinning it as we went. When the project went into production we used the documentation again and it worked like clockwork. When we needed to re-implment the server in an emergency, working from the documentation it worked like clockwork. I know that was good documentation...
Other stuff I've returned to and had no idea what's going on - that's bad documentation.
