For every pair of eyeballs, there is a different preferred way of seeing documentation. The spectrum seems to range from 'More is better' to 'Less is More' to 'The Source Code is the Docs'. This seems to be tied to individual learning and cognitive styles, therefore one is not very likely to discover any 'single right way' to do it. The variation in individual preference is almost like a (mutable) fingerprint.

Here is an example of something I have been using, which has worked well for me.

### <region-file_metadata>
### main:
###   - name    : tryPopupDialog
###     sbty    : perl script
###     desc    : here we try to pop up an input dialog box using perl
###     date    : Wednesday, October 06, 2004
### see_also:
###   - caption : tk documentation
###     href    : href="c:/docs/documentation/tk_docs.htm"
### generator:
###   - caption: this file was generated using a skeleton template
###     href:      href="c:/docs/new_file/new_perl_script.pm"
### </region-file_metadata>
[download]

Highlights: 1) It's eyeball friendly and machine readable (YAML); 2)The 'href' items work like hyperlinks that I can click and 'jump to' in my text editor or IDE. 3)The code uses as much auto-generation as possible so I do not have to retype things like the filename or the date. 3.5) The outline is flexible, and can be more or less detailed based on the project (you are not limited to 'main see_also' categories, put whatever you want in there. 4) The machine-readable format makes it easy to convert to POD, JavaDocs, Python Docstrings, or whatever other 'fingerprint' I have to match to make whatever project manager happy ;-) 5)The basic format is universally compatible with any programming environment that supports comments.

One discovery that no one else has mentioned, however, is that if you are serious about "good documentation" an important consideration is *consistency*. The reason why is because as you evolve and grow as an individual, so will your working style. As your working style evolves, you will go through different 'phases' ... each of which will be apparent in your documentation (among other things). It may sound like a contradiction, but as you change in each 'phase', make sure you stay consistent. In other words, you should be able to go back over your work through the years and identify whatever 'phase' you were in when you created it. "That's the phase where I thought that comments on every line was essential" ... "That's the phase where I preferred minimalism" (and so forth).

Here are some practical tips that may (or may not) be worth your consideration.

• Leverage the power of 'automatic boilerplate' so you don't have to type everything out by hand each time. I've never seen a consistently-documented work product that didnt have some kind of 'keystroke-saving-fill-in-the-blank-style-time-saver' for the people doing the work. Obviously, Perl is great for this kind of thing.
• Leverage the power of 'hyperlinks'.For any sizeable project, there will inevitably be bits and pieces of inter-dependent, semi-consistent documentation strewn about. Find a way to make connecting the dots as *easy as possible* for your working style. If you dont have something brain-dead simple, you wont use it. CTAGS is an example approach, there are many other ways to do it.
• Learn to distinguish when documentation is unecessary. Some work is like a quick grocery shopping list that you will never use more than once. Other work is like a Physics Textbook that you intend to sell internationally. Obviously, the level of necessary documentation is contingent upon your ultimate goal.
• Try to find a nice balance between 'eyeball readable' and 'machine readable'If you have a documentation system that is 'eyeball friendly', as well as easily parsed by some kind of program or script, and you are satisfied with it, you have reached a major milestone.