Last week we learned a few tips for writing better documentation, and talked about why good documentation is so important. Which seems self-evident, but some folks aren’t getting the message :). Today we’ll talk about letting clear, precise examples do the talking, and why being strictly literal is so important.
An unfortunate amount of computer documentation is so terse it seems as though the writer had to pay by the word. While it is possible to over-explain, that’s hardly ever a problem. With computers we’re dealing mostly in abstract concepts, so don’t be shy about spelling out even details that seem too obvious and basic, because to a lot of readers they won’t be obvious and basic.
A picture is worth a thousand words, and so are screenshots showing exactly what you’re talking about. For command line programs it’s even easier than creating screenshots, just copy and paste the text. You want to be as literal as possible, because computers demand precise literal commands. They can’t read your intent or waving hands, only what you type.
Here is an example of a too-terse explanation:
“Use the p option to print to screen, and the v option for verbosity.”
Which is OK, but doing it this way makes it crystal clear:
“Use the p option to print to screen, and the v option for verbosity, like this:
$ foo -p -v
You can combine options like this:
$ foo -pv
Increasing the number of vs, up to a maximum of four, increases the level of verbosity, like this:
$ foo -pvvvv”
That simple example shows a number of important details: running the command as an unprivileged user, the correct number of dashes, and case. It is also helpful to give abbreviated examples of correct command output so your readers know when they are running the command correctly. Your readers aren’t stupid when they don’t understand vague instructions, that’s a flaw in the instructions.
There are two useful approaches to computer howtos: one is a literal listing and explanation of all the options for a specific command, and the other is a task-oriented approach. The first is typical of man pages, and the best man pages also include a lot of examples demonstrating how to accomplish particular tasks. For example, man nmap is a lengthy and thorough reference with both the traditional terse man page format, and a lot of detailed exposition and task-oriented examples.
Taking a task-oriented approach is especially valuable when you’re teaching something more complex than a single self-contained command, such as putting together a mail or Web server. Unix/Linux has a tradition of stringing together small, specialized programs to perform larger tasks, which is a slick, efficient way to customize and perform complex tasks, but not enough of a tradition of spelling out what pieces the user needs to do a particular job. I’d say the biggest hole in Linux documentation is this sort of howto.
Always keep in mind that everyone started out as a beginner; no one is born knowing this stuff. The gods smile kindly on patient, helpful teachers. Come back Thursday for one more installment in this little series, how to get paid for writing howtos.