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?"

Re:And after you're done?

[RazzleFrog]

When all of your code is documented, you'll become expandable

Is that because you'll sit back and eat lots of twinkies? I think the word you are looking for is expendable.

obvious joke, sorry

[Graspee_Leemoor]

"I have been charged with writing lots of documents"

...In the trial of the /. submitter vs the hacker community the defendant was found guilty of writing documentation. He also asked for several charges of using meaningful variable names be taken into consideration.

graspee

Re:PEBKAC

[iamabot]

I blame society.

Re:Ten Reasons Why TeX/LaTeX is Better than Word

[CatherineCornelius]

There are no LaTeX "macro" viruses.

Unless you count the liveware virus that makes you want to escape every period\. I'd call that pretty macro\.