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

Out of curiousity

[Sheepdot]

Just out of curiousity, what are you writing documentation for? I myself would approach the problem according to what kind of software it was, and who the intended audience was.

A point about M$ word

[Anonymous Coward]

It will do versioning. See the menu file/versions

Documentation is not evil!

[deblau]

In fact, in most projects, documentation is more important than the code itself! This rule holds for all programs you intend for someone other than yourself to run (or, heaven forbid, debug later). My general rule of thumb for doing projects is:

1. Do feature reqs (10%)
2. Do design spec / unit spec (30%)
3. Do documentation (30%)
4. Write code (15%)
5. Beta-test / debug (15%)

Notice that design and documentation take up more than half the time on the project. Implementing the code becomes very easy with good, fleshed-out design and documentation.

As for solving your problem, I generally write documentation in-code using one style of comments and line-by-line comments using another style. Then forming docs from the code is easy: write a little perl script to extract the block comments, and format as you like.

Re:Documentation is not evil!

[FortKnox]

but you write the documentation as comments to the code you haven't written yet

ABSOLUTELY!
You should design every object and every function (down to what the functions input and return are) before coding everything. You should be able to write comments on the function (on the function, not in. Even having stubs for the function) before it is written. Then, you know EXACTLY what the function needs to do when you code it. You even have a nice reference doc for your teammates (if you use javadoc with java).

I've taken this approach MANY times, and I can't tell you how SIMPLE it is to code with this. Its like a homework assignment "Write a function foo, that takes two integers, adds them, and returns it as a real". The code practically writes itself. And the project manager usually doesn't have any trouble tying all the objects together.

I might as well add that this is a great technique to make open source work well and fast.

Re:Documentation is not evil!

[Anonymous Brave Guy]

You should design every object and every function (down to what the functions input and return are) before coding everything.

Sorry, gotta disagree with that. The place of design docs is not to mandate the details, like the exact function inputs and outputs. The place of the design docs is to paint the big picture, perhaps down to assigning the responsibilities to the major building blocks of your code (principle functions, classes, etc.).

Requirements change. This is a fact of life. No real project I've seen since I was a student had requirements that stayed fixed, or even close to fixed, during a whole development cycle. As a result, your design must change.

Furthermore, your initial design will probably be flawed in many ways you don't anticipate until you start trying to implement it. Unless you're copying an algorithm out of a textbook or a design you've used before, you'll be lucky to be even close to your final design on your first pass. As a result, your design will evolve.

If you attempt to record every little detail in the design docs, two things will happen. First, you will cripple the pace of development, as you spend more time updating paperwork than you spend developing. Secondly, your design docs will rapidly become out of date, and hence useless anyway.

The correct place for comments about the details is in the code. This is where you should record the exact input/output parameters of a function, the behaviour in error cases or the meaning of a little helper function. A combination of descriptive names for things and judicious use of comments will do far more for you than a 500 page printout of last month's code base.

Making your code its own detailed documentation allows for fast prototyping -- often the quickest way to find a good basic design -- and for ready modifications as the design evolves. This leaves design docs free to do what they should: recording the overall design.

Welcome to the 21st century, where the waterfall model dried up.

Re:PEBKAC

[mcelrath]

Uh, wrong.

If an application crashes, it's the developer's fault. Period. End of story. It is NEVER the user's fault.

To answer the article's question. I recommend LaTeX, LyX, latex2html (comes with LaTeX), and dvipdf (comes with ghostscript).

--Bob

LaTeX seemed the simplest way

[StormC]

I've been writing documentation for a little while now and LaTeX always seemed the best way to solve the problem. You can make nice pdf and print version. Yes it takes some time to get use to and most WYSIWYG people don't like it but it rocks in CVS.

Another Great Benefit of Java

[Enonu]

Javadocs are one of the best resource I have at my disposal for documenting my programs and reading the documentation of others. It's a wonder something like this wasn't in mind for every major language ever conceived. Never seen them before in action? Here's a link to the docs on Sun's website. Upper left corner is the specific package you want (like namespaces). The default view is all classes. Lower left is the classes for the current package chosen. The main frame contains the specfic documentation for that class. Everything is hyperlinked to everything else, so getting from one relevant document to another is cake.

I believe there are other systems that implement a Javadoc like utility for other language. Do a google for "Javadoc for C++" for example and plent of links show up.

No question - use LaTeX

[jelson]

I grappled with exactly this problem for years. I wanted something that would give me superb quality Postscript/PDF, good HTML, and at least passable ASCII text. (In 1994, it was still important to distribute ASCII documentation; not everyone had a web browser.)

I went back and forth with all sorts of things: SGML based solutions, a few more "proprietary" utilities, etc. Finally, the latex-to-other-format conversion tools got to be good enough that I could use LaTeX as my primary format.

My most recent documentation is for FUSD, a Linux framework for user-space devices. The original documentation source is LaTeX. Simply running LaTeX gives you DVI, which you can convert into publication quality Postscript. Using pdflatex (NOT ps2pdf), you can also create very high quality PDF, which includes a real PDF table of contents, cross-references, and URL links. Finally, using latex2html, you can create almost native-quality HTML documentation. And, if you really need ASCII, you can get a reasonable rendering by running lynx (in its ASCII-dump mode) over the HTML.

latex2html comes with special LaTeX macros that let you specify hyperlinks inside your document. They are rendered as real hyperlinks in HTML, and footnotes in the printed versions.

Use DocBook and document as you code

[UsonianAutomatic]

Or document even before you start coding, as someone else already mentioned; I've found that starting documentation early on accomplishes two things:

1. it helps the planning process immensely by forcing you to really think about what your code is going to be doing, and
2. it ensures that the documentation end of the project doesn't get short shrift; once the code is done it's too easy to gloss over the documentation when the next project is breathing down your neck.

DocBook easy to author with... the pain in the neck part is setting up a processing environment with Jade/OpenJade/DSSSL, but it's well worth it. It's also possible to use XSL/XSLT to process DocBook XML, but I don't know how involved the setup is. YMMV.

Another vote for LaTeX here

[Anonymous Brave Guy]

Put me down for LaTeX as well, please. In its favour (in this particular context)...

1. It takes input in a text format. Use CVS, your favourite editor, etc.
2. It also produces excellent quality output, and generating HTML, PostScript and PDF output are all straightforward with standard tools.
3. It can generate things like cross-references, tables of contents and citations very easily.
4. There are good packages available for free that can typeset code right out of the source file.
5. There are freely available and very powerful diagramming tools that plug right in. (Anyone know of a speciality UML drawing package, BTW? The usual tools are OK, but I've never found, say, some Metapost macros to make it completely trivial the way it could be. Surely someone must have written some!)
6. The maths typesetting is all there if you need it, of course. That's very useful if you're working on a scientific app and need to document the algorithms as part of the design, and it doesn't get in the way if you don't need it.
7. It's available for minimal money and effort.
8. It's highly extensible. If you need to do something that doesn't come as standard, you almost certainly can (and someone else almost certainly already has, and put it on CTAN for you).

The only downside I can think of is the learning curve. Basic LaTeX use is fine, but for really good output, you're going to want your own class file and/or packages. That's fantastic once you've got it -- all your docs follow a consistent style, and you can make it easy for newbies to learn the tool. Someone has to be pretty sharp to write the class/packages in the first place, though, or you have to be prepared to buy in expert help for a couple of days.

Ten Reasons Why TeX/LaTeX is Better than Word

[klund]

1. LaTeX math mode is a thing of beauty. Equations come out looking correct. Mathematical expressions in Word are treated as an afterthought. Equation editor is evil.
2. TeX is guaranteed to be bug free. The author, Stanford Professor Donald Knuth, will send you a reward check is you find a bug. The reward is currently $327.68 (that is, 2^15 cents).
3. TeX is free (as in beer) and free (as in speech).
4. TeX has real comments. Anyone who doesn't comment their code is an ass.
5. TeX provides a full, turing-complete, language. The text produced by your input file can be the result of conditionals (which I use to reuse sections in different documents) or the result of complicated calculations. In the TeXbook, Knuth demonstrates the power of the TeX language by defining the \primes{n} command, which calculates and print the first n primes (see page 218).
6. There are no LaTeX "macro" viruses. You can safely receive LaTeX documents by email and not worry about it reading your OutLook address book and mailing copies of itself to all your friends.
7. LaTeX has no GUID (Globally Unique Identifier). Word documents are embedded with a code than can be traced back to your computer (the police captued the author of the Melissa virus by tracing his GUID). Big brother Bill is watching!
8. LaTeX versions are not incompatible. The file format has never changed. I have LaTeX files from 1989 that work without problem in the latest version of LaTeX.
9. There is no undo feature in TeX. This is a good thing. No one can ever seen earlier versions of your TeX document by pressing the Undo button.
10. LaTeX documents are small and lean. What's the smallest Word file on your computer?

Word is horrible

[coyote-san]

MS Word is about the worst tool around for writers.

The problem is that it forces, FORCES, you to deal with presentation issues at all times. When I'm writing, I want to focus on the content. How is the material broken down into major sections, into chapters, into topics? What information needs to be presented before a new topic will make sense? What topics will be treated as reference material, needing easy lookup?

This is hard enough to do with regular interruptions, but with text it's possible. I write an outline, DocBookify it, then write straight text within it while using minimal tags. When I'm happy with the content, I work on presentation (and usually loop between them a few times.)

But Word is so damn helpful that I'm constantly interrupted. I mispelled a wrod or two, gotta fix it NOW. Esp. with the increasingly intrusive "autocorrection" that insists on "fixing" things. (And don't get me started on it's ideas of what a properly formed URL looks like, never mind the RFCs.) There's the issues around the Redmondian English. My grammar isn't perfect, but highly technical material often requires extremely complex sentences to adequately convey the nuances. Green lines are another distraction. Then there's the whole issue of lists, tables, indentations, etc. sucking your attention because you're forced to deal with presentation before you're entirely sure what's going into them. (Two tables or three? What drives columns, what drives rows?)

Is it any wonder I, and many other people, find Word documents to be unusually vacuous? Not every text document in a Jon Postel RFC, of course, but there seems to be a direct correlation between the meat in a document and its original format. Straight text seem to be written to HS or college level, Word documents seem to be written to Jr High level at most. The problem is the polish - Word documents often strike me as first or second drafts, not finished documents. But they sure are pretty.

Re:PEBKAC

[mark_lybarger]

yes, if your application needs (or can) work with a specific hardware which requires a specific configuration, then your application should take responsibility to ensure that environment is present. aborts are bad! they should not be tolerated. an application should not allow a dumb user or dumb hardware to crash it.

I switched

[fireboy1919]

I wrote a publication (16 pages, IEEE format) for Word and it was a REAL pain. Word stored the whole document in memory, which actually meant that part of it was cached to hard drive. I work in the Field of Computer Vision, so I necessarily had about 10 megs of images in there. Occasionally, that would be too much for the operating system, and I'd have to wait 15 minutes or so for the memory manager to catch and resolve some thrashing issues.

Also, every time I changed anything at all, Word would move around the pictures and mess everything up - even though I had all the pictures positioned as "absolute." At the end of the publication, any 3 minute change at the beginning of the document took half an hour to fix.
For the next publication, I did everything in Latex. The added bonus there was that format is separate from content, and the format descriptors where already written by IEEE (and by my school for my thesis).

No, you're an idiot

[RebornData]

I use Word almost every day, and while many of your comments are true for default behavior, you clearly have not attempted to actually learn the program. To take the issues in the order you cite them:

1. Word actually doesn't force you to deal with presentation issues at all times. Are you familiar with outline mode? I usually do my first drafts in outline mode, which allows you to focus entirely on content and structure independent of formatting. Outline mode works with styles to specify formatting globally for a given level in the outline. So if the top level in your outline applies to chapters, you can easily define a chapter heading style that will be automatically applied to all the top-level items. It really works well.

2. It's been said already, but it's worth repeating: Real-time spelling and grammar correction are really easy to turn off. Really easy.

3. Lists & indentations. You should learn how to use styles. This is exactly what they are for. For example, my default template has a "bullet list" style. If I want something to be a bullet list, I apply this style to it. The "tags" aren't visible, but they effectively are there. If I ever decide that a bullet list needs to be indented differently, or have square instead of round bullets, I can make the change once for the style. Once you've set up your default doc template with a reasonable set of styles, you never have to worry about presentation during early stages.

4. I don't understand what you say about tables.

5. "Word documents seem to be written to Jr. High level at most"? What the hell? This is broad generalization at it's worst. I bet more doctoral dissertations are written in Word than anything else. Although I did get a good laugh thinking about what the average grade level of a /. post would be...

Now, I'm not saying Word is the end-all be-all. I'm just saying that you're an idiot because of the 10000 things wrong with it, you've picked issues that are almost univerally untrue, and simply reflect that you haven't learned to use it.