Poorly written documentation, indeed no documentation at all, can turn completely unusable the best programs or package.About documentation file format: man, chm, html, xml, pdf something else?
LV For presentation of scripting reference material for extensions and at least simple application references, if to be used on unix, man documentation needs to be able to be generated.
For presentation of more detailed application doc, I prefer html over PDF simply because it is generally easier for me to read the docs that way.
Another potentially useful format is the wikit format; starkits have been making use of a wikit for help information for some time.
However, the Tcl doctools format is pretty good for preparation purposes.
About documentation tools: editors, screenshot utilities, i18n...
The simpler the better, for editors.
kroc According to me, a perfect doc generator would be:
Something based on expand maybe?
About content itself: what is desirable to do and what to avoid to write a good user manual.
Please give here your opinion, your own choices and why.
RS: Like many of us, I document less than I code. Luckily, I rarely have to deploy to non-expert end-users. But even running my own apps after some time, I like concise online help best, e.g. htext - and sticking to accepted standards, like having the Exit command at the bottom of the File menu...
But if it has to be documentation that can also be printed out, I prefer HTML as the most portable, even to PocketPC, editable, simple, yet decent in printout. Oh, and especially pages at the Tcl'ers Wiki - most easily reached from any online box :)!