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

[ot] Anybody ever tried developing their own?

[kitts]

I've been wrestling with this problem myself lately, as I'm going to be getting into putting some seminar stuff I've written for my students into a portable format. Pretty much all the options have their drawbacks, and I figured what the hell, I'd roll my own.

Has anybody tried doing this? What approaches did you try? What language(s) did you use for parsing it? What problems came up? What general format guidelines did you have to settle on? Anything that you wanted to do and couldn't, for whatever reason?

Re:[ot] Anybody ever tried developing their own?

[RonBurk]

I just write in a very simple subset of XML, creating new tags whenever needed. The subset is simple enough that the C function I use to parse it is about 120 lines (speed of parsing is blindingly fast enough to never be an issue).

Once the documents are in XML, then I change them into whatever I want. I use a custom C program to turn a bunch of XML files into input for PDFLaTeX when I want to get a PDF file. I use XSLT to turn them into HTML. I use LaTeX to get PS. HTML, PDF, and PostScript are about the only output formats I care about at the moment, but I'm betting I'll be able to fairly easily transform the XML into any other output format I need in the future.

I played with DocBook, and would be more likely to use it if I expected other people to maintain my docs in the future. However, by evolving my own set of tags, I found it much easier to remember what does what, and of course to make the functionality exactly fit my needs.

Re:A point about M$ word

[Gzusfreak]

My washing machine will do dishes too, but they'll probabally come out broken... Hey same with Word... it does versioning, but it'll probablly come out broken.