Comment Outside of the code, all documentation is worthles (Score 5, Insightful) 312
I currently work for a company that has instituted an incredibly restrictive development methodology they bought from a big consulting firm. It requires multiple forms be filled out for every program written, every requirement for every program written, every request for every change to every program or application written. All of these reviewed by coworkers who are not about to alienate team members, and reviewed by lower management who want to look good to upper management by having everything go smoothly.
These documents are then stored on the LAN. To never, or rarely ever, be read again.
The one thing it does not enforce or require, is meaningful documentation in the code itself.
It doubles, or more, the time it takes to do everything. But it does nothing to stop the mistakes any better than the procedures that went before. If anything, it finds less errors, because we were not given more time to do this double or more amount of work. So time is so compressed, we do not have time to do anything other than get it working and get it in.
One thing it does do very well, is prevent problems from getting fixed. The only people that will start a change effort are those that notice a problem and are affected by it enough to have it cause them problems. Otherwise no one wants to go through the bureaucracy to kick off any sort of change effort, which leaves a lot of ticking time-bombs in the infrastructure configurations, application designs and application code.
The only place documentation is good, is if it is meaningful, and in the code, where it is readily findable and far less likely to get lost, short of some fool deleting it.
Documentation located anywhere else will be lost, or obsolete many more times than not, before you ever really need it.
If anything, documentation in code should be reviewed by people with absolutely no connection to the application it is for. If it is good enough for them to figure out an understand what is being done, and more importantly why it is being done, only then is it worth anything more than the bytes is written with in storage.