Writing Documentation

twms2h queries: "It is everybody's favorite task, the worst part of programming: writing the documentation. I have been charged with writing lots of documents, some smaller some larger, most of them documenting programs I wrote myself. In order to avoid the torture of fighting with Microsoft Word all the time (which crashes on me regularly) I am looking for an easy way to get printed and electronic (HTML/PDF) documents from as simple a source as possible. I have looked into several of the processing tools that are available on the net." Below is twms2h's take on a few of the documenting systems available. The preference is to keep things simple, editing ASCII files to produce high quality documentation. Are there other tools some of you know of that might prove to be better solutions?

"So far, I like aft, mostly because it is simple to use, and gives me nice result as HTML. Unfortunately HTML is not enough, since I also need a very good looking printable version.

There are alternatives like DocBook, which I could not get to work and udo (Page is German, get the translation from the fish) which I have not yet looked into very closely.

Then of course there is TeX and any number of WYSIWY-won't-G word processors. I haven't used TeX much, I only tried my luck in writing a few letters (and found out that it is not suitable for this). I went through hell when I wrote larger documents with various versions of MS Word and I am not really a fan of Star Office even though version 5.2 has not yet crashed on me (however 6.0 beta did). KWord, part of KOffice doesn't seem to be stable enough yet.

I would prefer a simple ASCII only format as the source for being converted to more complex formats anyway, especially since it could be easily put into CVS for version management (Anybody tried that with MS-Word documents? Don't!)

As all these projects show I am not the first one faced with this problem. I wonder what experiences Slashdot readers have had with these and other packages?"

Comments

PEBKAC

[way0utwest]

Not to disparage any other product, open source or not, but if Word is crashing on you regularily, you are doing something wrong.

I've use all versions of Word from v2.0 to 2000 (no XP) and while I have had crashes, they are rare. I have written over a hundred articles, averaging 1300 words and a book using Word and have lost very little.

Re:PEBKAC

[darkwiz]

This is just short sighted. Application crashes are not ALWAYS the app developer's fault. In many circumstances, they are. But the app developer may be using libraries that the user can upgrade/interchange, that the app developer has nothing to do with implementing (such as glib). If there is a bug in the library they call which causes an obscure crash or the user changes the library to an unstable version, you can hardly blame the app developer.

Secondly, a surprising number of "crashes" aren't application crashes - they are hardware issues (conflicts, heat problems, failure, etc), driver issues (some call they make to a graphics routine tickles the video driver in a bad way), and OS problems (deadlock, Microsoft, bugs). What most people interpret as a crash (especially in OS's where a single application can easily take down the entire system, like Win9x), looks identical in these circumstances; the computer ceases to respond. Even experienced computer users can have a difficult time assigning blame.

And to be on topic: when selecting a documentation system, look for one that avoids redundant work. With lesser tools, you will have to update documentation in your code comments as well as in your design documents. Maintainence is everything here, and if you have to double commit all alterations, you will become frustrated very quickly. Hence why a source code parsing tool [like Doxygen] is probably the better choice, regardless of the features of other programs.

Docs?!? Feh...

[Wee]

Documentation? See the README for what I think of documentation.

-B