Posted
by
Cliff
on Thursday January 10, 2002 @03:58PM
from the the-unglamourous-side-of-development dept.

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

...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.