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 :)!
As I've found nothing really adapted for it, I planned to do it myself.
Purpose: create a very simple editor for end-users manuals (lets us call it Tkdoc). This editor itself will use a tcl like syntax that will be parsed on output to produce html. The parsing will be done according predefined macros (see below).
Goal of Tkdoc: make writing end-users manuals easier and quicker. Make manuals easier to translate, to update and to correct. Finally give a kind of uniformity for look and feel of tcl and tcl apps manuals.
Functions envisaged: Very simple GUI with an edit window (notebook based). Menu with standard file operations, parsing button, preview button and screenshot button.
Tkdoc file format: A single macro+text file with screenshots images datas at the end. At the point, predifined macros could be:
Please feel free to add your own ideas before I start it, so the result could be as good as expected for everybody.