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. ---- [Michael Schlenker] Tkdoc looks very much like [doctools], but probably with a slightly different focus. Could those efforts be merged? There is not yet an GUI editor for doctools would be a good way to start. [AK]: I would welcome a GUI editor for doctools. This could start out separately, but ultimatively this should be made a subcommand of [dtp] (IMHO). [AK]: Regarding Tkdoc it is quite similar, and thus a bit of a redundant effort. From my POV we can use parts of doctools (call, arg, method, option, ...) to describe a procedure and place that as comments in the code, either before a procedure, or inside. Then we just need a tool to extract the information and weave it together into a complete manpage. See also [autodoc] for such a tool, except that it uses it own markup for the embedded documentation (it predates doctools by some years). [kroc]: All this is more adapted to tcl developpers manpages than real end-users manuals Tkdoc is suppose to produce. ---- [ro] It's a waste of time to create yet another format. Instead of documenting, you will be coding (a common pitfall). Just start documenting now, in whatever you know (roff, html, LaTeX...) You can always hack it into another format later. Docs now is better than perfect docs later. ---- [AK] Note that [doctools] as base format makes conversion to Latex, nroff, html easier. IOW, not hacking into a different format later, but automatic conversion without hassle. ---- [LV] Over the years, people have suggested various [SGML] or [XML]/[DTD] solutions to documentation. The problem with many/most/all (??) of these has been that while getting the words of the documentation is awkward enough, then the effort of adding ''appropriate'' formatting results in a loss of focus. If one is formatted as they write, as much time is spent worrying about the formatting as is about the content. If one attempts to format afterwards, the resulting text becomes difficult to edit. [HTML], Tex, nroff and PostScript are likewise an increasingly difficult series of formatting languages. Some would argue that MS Word resolves this - the text can be input directly, editing can, in general, remain focused on content. However, the problem with Word is that it may work well for Windows platform users, but is not easily generated and maintained on other platforms. What do other language communities use? Perl has their '''Plain Old Documentation" format (aka POD). ---- [kroc]: As [AK] wrote above, Tkdoc also could be a simple [dtp] frontend. I'll do that with pleasure instead of starting from scratch, but in that case, I'll need to add/remove some doctools tags (like image support, restricted nested levels, etc..). Moreover, [ak] more or mess planned to update doctools tags, maybe we could define here what should be kept, add or remove for ''this'' particular purpose? ---- [LV] What did you have in mind that would need to be removed from doctools? ---- [kroc] I don't really need to remove something to doctools. In fact, it will be enought for Tkdoc purpose to use only a limited set of doctools tags. The less choices the writer will have, the quicker the manual will be written. I think the list I wrote above is enought to write a comprehensive end-user manual. ---- [Category Documentation]