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

WordPerfect

[mkoenecke]

Remember WordPerfect? Version 9, SP4, is rock solid stable and does not suffer from Word's inability to handle long documents. (The primary culprit: Word's continuous repagination and reformatting, required by the document structure.) Versioning is supported, and WordPerfect, unlike Word, has the native ability to generate PDF files. Version 10, SP2 does even better, formatting hyperlinks automatically in PDF files, but I won't recommend it yet because there's a nasty interaction bug between it and Mozilla.

Not to mention WordPerfect's ultimate advantage over Word: Reveal Codes. In Word, any fouled-up formatting can only be fixed by *different* formatting. In WordPerfect, you can *remove* offending code. And it's more customizable, doing things the way you want them done, not the way Microsoft dictates. I could go on about dozens of other advantages, too.

Oh yeah, there are Linux versions available too (albeit using Wine).

Frankly, I'm amazed that any person with technical knowledge and expertise would use Word by choice.

Re:HTML

[ChristTrekker]

You missed one of the nicest features of using HTML/XML for documention: the fact that with CSS you can get basic content transformation.

What does it mean? It means that you can have rules for online display (that we're most familiar with), different style rules that kick in only when you print (implemented in Mozilla and Opera), and different rules only when you are projecting a presentation (implemented in Opera). This lets you make it accessible on the WWW, yet write your documentation only once without futzing with a nicer "print friendly" copy. If you do a presentation, you can point your audience to the very URL you're using for their later reference. Less chance for confusion.

XML, XSLT and Docbook - a near-perfect solution

[swillden]

I've been using XML and Docbook for a while now, and I really, really like it, particularly if you use Docbook as an intermediate format rather than what you actually write your documentation in.

For example, I've got some really nice stuff for building use cases in XML. I created my own DTD for a use case language (which I call UCML) that allows me to define actors, use cases, goals, glossary terms, etc. Use cases consist primarily of a sequence of steps (nestable) with links to actors, terms, other use cases or steps, goals, etc. along with some other tags that define the name, extends relationships with other use cases, termination states and conditions, preconditions, business rules, etc.

I also have some XSLT stylesheets that do a number of nifty things with these UCML documents. One stylesheet transforms UCML to HTML, complete with every imaginable hyperlink, tables of contents etc., and even deduces a bunch of relationships which it documents (and hyperlinks). For example, if a use case mentions an actor or another use case in its steps, the stylesheet adds a section to the HTML description of that use case that documents the fact that this use case uses (in the OO sense) that one, or that this actor participates, and adds similar information to the descriptions of the use case and actor that are referenced. This is just a sample, the stylesheet does a lot more, and produces very *usable* and consistent documentation.

Another stylesheet acts as a sort of garbage collector. Phases (groups of Use Cases intented to implemented together) and Use Cases can be marked as "dead", in which case the UCML->HTML stylesheet will "hide" them (they won't show up in the output). The garbage collector stylesheet takes this a step further and analyzes all actors, glossary terms, entities, goals, etc. and produces a new UCML document that does not include elements unreferenced by a "live" use case. So, I can mark some currently uninteresting use cases as dead, run the garbage collector, run the UCML->HTML stylesheet on the result and get a nicely formatted document that contains only the supporting information required for the included use cases.

HTML is not ideal for printing, though, and this is where Docbook comes in. I have a UCML->Docbook stylesheet that does essentially the same things as the UCML->HTML stylesheet. Then I can convert the Docbook to PDF, Postscript, TeX, etc.

I've also created my own XML languages for component models, architectural decisions documents and others -- it's pretty easy to gin one up whenever I come across another sort of highly structure document I need to write. Plus I have one that I use for simple, less-structured documentation that just provides sections, paragraphs, etc. Mostly I just have whatever->HTML stylesheets for most of these, since they're all intended to be read by developers who are less insistent than end-users on having printable formats.

So, I have nice, text documents that I can use EMACS on, manage in CVS, etc., stylesheets I can fiddle with (when I get sick of writing documentation I can always spend a little time improving the stylesheet code and justify it as "documentation" effort :-) ) and everyone else gets really nice docs from me. The biggest downside is that other people (non-programmer types who are uncomfortable with tagged text) are often uncomfortable with trying to edit my documents (sometimes it's a good thing, as it allows me to retain the "power of the pen", sometimes its bad as even trivial updates must pass through me).

The next steps with UCML are (1) figure out how to establish and maintain XMI-documented use cases and UCML-documented use cases and (2) write a WYSIWYG-like tool for editing them, for the tag-averse.

BTW, if anyone is interested in using the stuff I've described, drop me a line. I've been thinking about putting it up on SourceForge, but don't know if there's enough interest to make it worthwhile.

In praise of DocBook

[PhilRod]

Nobody seems to have mentioned the great advantages of DocBook here. Having written some bits of documentation for KDE, I've seen some of DocBook's advantages:

• First off, it's fully compliant SGML or XML, whichever flavour you prefer. DocBook documents are stored as nice plain ASCII which can be processed with any SGML/XML tool you happen to have lying around.
• Output options are virtually unlimited. IIRC, HTML, man, texinfo, plain text, (La)TeX and anything else you care to mention are available as output formats, with XSL providing a way to produce your own custom output.
• The Crunch: Text is marked-up for what it is, not what it's meant to look like, so you needn't know a single thing about formatting while writing content and vice versa. You know the advantages of using CSS instead of hard-coding HTML. Well, they count for DocBook too.
• Nifty features like creating tables of contents from the source and all that sort of thing that you thought only TeX could do.
• I suppose I should mention that it's extensible, hence the XML version.

--PhilRod

TeX gone? Nope.

[Grendel Drago]

Uh, no.

METAFONT is pretty much integrated into TeX if you're using... well, I've only used teTeX and MiKTeX, but there are scripts to autogenerate any fonts that are needed.

And... well, you can't compete with the userbase. It's been a standard for nearly twenty years. The original program is probably as close to bug-free as any large piece of software can possibly be. Did I mention the enormous userbase?

TeX is far from dead. It's Knuth's dream that a TeX file written today will be compilable and readable in a hundred years. Given how entrenched the system is, I think this is quite likely.

-grendel drago

Be a little wary of DocBook

[beej]

I've done Beej's Guide to Network Programming in DocBook (it used to be HTML). It works quite nicely for HTML output with NWalsh's stylesheets.

What was hard was getting it set up, and getting help out of the DocBook people in the know. (They can be pretty unapproachable sometimes.)

What was also hard was getting print output to work nicely. I was running fine for a while until I upgraded openjade, and then blammo--two-sided print output doesn't work anymore. Openjade simply refused to put the two-side directive in the TeX output, so I did it myself.

And what is it about my document that causes openjade to take 3 minutes to pump out TeX output, when it does the HTML in about 5 seconds?

Why is it that when I put two tables on the same page openjade/jadetex doesn't take that into account and keeps printing text off the bottom of the sheet?

The other place I've looked is Xerces/Xalan/Fop at Apache. I like the Formatted Objects idea, and it seems pretty sound. Also, the whole thing was about 827 times easier to set up than the jade stuff. Unfortunately, the code is alpha and doesn't work very well, sometimes crashing during the render.

"How does ORA do it, then?" I hear you asking. They have custom in-house tools for processing DocBook that have been in development for some time. Word on the street is that they might be releasing them soon.

Conclusion: if you want print output, you might have trouble getting what you want with DocBook at this time. At least when I code TeX it does what I say. (I don't recomment plain TeX for documentation. Maybe LaTeX since it's easier to convert to HTML. And pdf(la)tex produces nice PDFs.)