documentation rant

Everybody knows that open-source software documentation sucks.

It doesn't, however, suck nearly as much as big-company proprietary software documentation, which Steve Holden characterizes as

Threep Nardling
To nardle threeps, select the Threep tab and check the Nardling checkbox.

... and so forth... a beautifully-typeset waste of electrons.

The questions we go to docs for are: Can I nardle a threep via SSH? I tried it, but my threep still isn't nardled. I got an "ERROR: Threep nardling failure" message. What now? If those questions aren't addressed, there's really no point.

These days, I do sometimes see open-source docs that address these questions. Most often, of course, you find answers to these questions in the user community.

Anyway, I suggest that, when users run into trouble, this is the preferable order of responses:

1. Change the program so that it acts as the users expected in the first place.
2. Use program interaction and informative error messages to guide users through problems without having to look outside the program.
3. Put the answer in the documentation - and make it easy to find or it doesn't count! Expecting users to comb painstakingly through 400 pages is not realistic.
4. Respond to individual questions via some sort of support process.

Small-to-medium FOSS projects are the best at responding in this order, probably because the same people - or at least people who know each other - are responsible for writing the program, documenting it, and answering user questions. At Big Software Corp., on the other hand, Support, Documentation, and Development are likely to be completely separate groups. The professionalization of documentation is deadly, because you get reams of nearly identical manuals that are pleasantly laid-out and nicely proofread, but completely unaware of realistic user problems. Support is painfully aware of user problems, but they have no process to tell Documentation and Development, "Hey, users keep getting confused here. Can we change the program and the docs to help them? Please? Because we'd really like to quit getting these questions?" (Perhaps some companies do have processes; I can only speculate, but I do know that I don't see evidence of it.)

Oracle, incidentally, only about halfway sucks in these matters, which is pretty good for a company so large. Their docs generally have some good, non-obvious substance, and sometimes - but, alas, only sometimes - troubleshooting information.

In short, I think you need users' pain to efficiently and accurately become developers' and documenters' pain, so that the causes will get fixed. Small FOSS projects have this kind of pain transfer built-in (when the authors publish their email addresses and invite questions). Everybody else should think about how to make it happen for their product.