in reply to Preferred method of documentation?


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.

a personal example

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/" ### </region-file_metadata>

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).

nuts-and-bolts tips for the trenches

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