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; [starkit]s 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: * platform independent for both editing and displaying contents. * very simple to use. * follow predefined formatting rules. * able to grab window or tk widget to include screenshots. 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 :)! ---- [kroc] 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: * [title ''string''] (Document title) * [sec ''title''] (Create a new level 1 chapter and its entry "title" in index. The section content (text, images and subsections) will end at the first following [sec]) * [sub ''title''] (Create a new level 2 chapter and its entry "title" in index. The subsection content (text and images) will end at the first following [sub] or [sec]) * [img ''name''] (Insert a image stored after [end] with "name"). * [tag ''name''] (insert a link target "name"). * [link ''target''] (insert a hypertext link to "target", target can be a section or a tag name.) * [index] (insert an hypertext index according existing sections and sub-sections). * [i ''string''] (output italic "string"). * [b ''string''] (output bold "string"). * [u ''string''] (output underscore "string"). * [end] (end of the manual). Please feel free to add your own ideas before I start it, so the result could be as good as expected for everybody. ---- [Category Documentation]