The Internet is full of software and hardware forums, tips, tricks, and howtos from all kinds of people. It is a wonderful thing that there are so many generous users sharing what they have learned. Chances are you’ll find better information from these outside sources than on the official project sites.
Naturally the quality is pretty uneven because it’s people from all walks of life contributing– young, old, non-native language speakers, and so forth. Nobody expects Nobel-winning literary excellence, but there are a few simple techniques for writing better documentation that anyone can learn.
It might be worth mentioning that decent documentation benefits everyone; I mention it because it seems that not everyone understands this. It benefits software developers because then users won’t pester them as much. (Don’t complain about getting asked the same question over and over– publish a FAQ.) Knowledgeable users help other users and figure out cool ingenious hacks. Users turn into contributors more easily when they don’t have to dive into source code to figure out anything. Having to figure out everything the hard way is a waste of time.
This all might sound odd coming from someone who makes a living writing Linux howtos, but way too much of it is painfully figuring out the basics. I’d rather be getting into fun advanced and creative things than having to continually start from the beginning. In my perfect world, the baseline would be thorough man pages detailing all commands and options, complete changelogs, and nice complete release notes. I realize this puts a burden on software developers, but I think it’s way past time to recognize that it’s part of the job. Nobody understands an application like its creator, and then other people can build on the baseline documentation.
man rsync Demonstrates Good and Bad
I love man pages. I’m glad that Debian packaging rules require that everything have an accompanying man page, and that there are a large number of online man page repositories. Sometimes this requirement results in lame man pages that say things like “Debian requires this to be here, but we don’t have to put anything useful in it.” But it’s still a good requirement. It’s the easiest thing in the world to type “man [commandname]”. Man pages work when everything else is broken.
man rsync is an example of a decent man page with a common flaw, which is the name and description are not very helpful:
“rsync – faster, flexible replacement for rcp
rsync is a program that behaves in much the same way that rcp does, but has many more options and uses the rsync remote-update protocol to greatly speed up file transfers when the destination file is being updated.
The rsync remote-update protocol allows rsync to transfer just the differences between two sets of files across the network connection, using an efficient checksum-search algorithm described in the technical report that accompanies this package. “
This presupposes an awful lot of knowledge on the part of the reader. Which brings us to rule #1 of writing good help docs: Don’t assume your reader already knows everything, because they don’t. Rule #2 is use normal English, or whatever language you use. Nobody was raised up talking like an over-literal Vulcan– we all started out in life talking like normal people. A more helpful name and description are something like this:
“rsync – a fast, efficient, secure file-transfer program that is used for quickly synchronizing directories and files from one location to another. For example, mirroring Web sites and making backups over a network, or to locally-attached drives.
The first time you run rsync it copies your files pretty much like any other file-copying application. After that, it transfers only the changes in your files instead of re-copying every file, so it is very fast.
rsync uses ssh by default to securely encrypt the transfer. The files are not permanently encrypted, only while they travel over your wires. Or wireless, as the case may be. “
Doubtless that can be improved, but at least readers now have a good idea of what rsync is for. The ones who are interested in protocols and algorithms can go research them; it’s more helpful to stay focused on the common starting points which are always “What is this for and how do I make it go?”
Changelogs
Nobody likes to be surprised when a new release does something differently and doesn’t tell you. That is a major cause of justifiable whining. Always have nice complete changelogs.
Release Notes
Debian and Fedora have wonderful release notes; they cover everything, include workarounds, and don’t leave users caught up in undocumented changes and broken apps. Ubuntu used to be the poster child for sketchy, useless release notes, and fortunately has improved a lot.
I suppose I’m going to hear from the “but nobody reads documentation so why bother” crowd. That is untrue. At the least decent documentation allows you to answer questions with “Please read the fine manual.” Assuming the fine manual contains the answer to their question, and it is complete and understandable.
Next week we’ll look at a few more easy tips for writing good, helpful documentation.