Stupid reasons not to document

What is documentation, in a programming environment?

At the top is user documentation: user and maintenence manuals.

Sales/marketing documentation: specifications, capabilities

Standards documentation: backing information that standards were followed.

Design/development documentation white papers, change requests, development meeting minutes

Programmer docs, library/package documentation, class/function documentation, line documentation

The best way to ensure that your project will become unmaintainable within a few years is to fail to document what the team is doing internally.

The develoment group should be involved in each of the development efforts, at least to ensure accuracy. That doesn't mean they should be responsible for writing a user handbook, or dotting the i's on regulatory documents.

You do not need to write a novel. You should not write a novel.

When a new programming effort is first conceived, write out a page or so, describing the main goals, perceived problems, proposed solutions, etc. This is the white paper. It is invaluable for future programmers' reference.

Each major programming unit (package, module, whatever) could sport a paragraph or two describing its contents and policies.

At the function level, it is useful to describe in a line or two what the function does (even if the name says that), what the arguments and the return value need to be, and any exceptions or error conditions that can be expected. Also, of the function is meant to be used with another interface (another function or class), that should be mentioned as well.

USUALLY some other programmer will some day use this again. It is very helpful to have a little guidance.

Line comments are best kept to a minimum, pointing out only things that are strange, things that might cause a later programmer time to figure out.

For larger projects, it is important to associate documentation with changes to the program, and there are software systems to do that... so that a change to the code is tested and re-documented. If such a system is well implemented, it can result in documentation being both accurate, and done mostly by people other than the programmers.