Back to article
Linux Bug #1: Bad Documentation (part 2)
The Many Faces of Documentation
November 19, 2009
In Part 1 I talked about the messy state of Linux documentation, and how telling users to rely on Google is not documentation. Good documentation is equally important as good code. Sometimes there is this attitude that developer time is more valuable and important than user or potential contributor time. I suppose it depends on how much a particular project wants users and contributors; the more friendly and helpful on-ramps into a project, the more users and contributors. Good documentation is a big step towards quality control; when everything is documented, including reasons why something is done a certain way, it's less likely to be forgotten, which increases efficiency.
Getting started is probably the biggest hurdle, and once that first set of docs is completed they go into maintenance mode and need only changes and updates. I have a theory that good documentation discipline also encourages good development discipline, and fewer senseless changes that tend to vex users. Like moving a button or changing a command name, or re-organizing menus-- having to document all these things means taking another look at them and deciding if they are really necessary.
Yes Users MatterIf you want other people using your software, that is. There is never perfect harmony between devs and users, but it's much better to respond to questions with a pointer to a FAQ or a manual than to ignore them, or to crab at them for asking, or worst of all, tell them to Google or trawl mailing lists. Web, forum, and mail list searches are for edge cases and troubleshooting, not for basic howtos.
"Documentation" covers a lot of ground, from basic man pages to glossy four-color books. Let's take a look at the different categories of documentation, and what is reasonable to expect.
man PagesMan pages are awesome. I love man pages. They don't require a graphical interface, which is nice when Xorg or video drivers are broken, they don't require Internet (assuming you don't have some weirdo distro that doesn't install them), and you always know how to find them-- type man commandname. Nice and easy. (We'll talk more about these, and other ways to find and use documentation, in Part 3.)
Command DocumentationWhether this is in a man page or some other form, documenting all the commands and command options in an application is essential. I shouldn't even have to say this. How else is anyone going to know them, telepathy?
Usage Scenarios and ExamplesThis is the next step up from command listings. Having a man page full of commands and options is better than nothing, and having lots of examples of real-world use is a hundred times better. When would you want to use this set of options or that, and when is foo preferable to blah?
Some tasks benefit from "big picture" howtos, and not just focusing narrowly on a single command or application. A classic example of this is learning to run a mail or Web server. It's not enough to learn just Postfix, Exim, or Sendmail because a mail server uses a lot of specialized servers and applications working together. Another example is doing audio and video production; this involves learning system tuning for best performance and low latency, and learning which of the multitudes of Linux multimedia applications work best and work well together. Including references to relevant companion apps and howtos, and describing how all the pieces fit together is a very helpful thing to do. I know, there are lots of pieces and lots of different ways to assemble them-- pick one.
Teaching a New FieldThis is the hardest. For example, you want to learn to use Audacity for audio recording and editing. You can't just "learn Audacity", you also have to learn audio concepts, terminology, techniques, and audio hardware. Another example is Digikam, the fabulous and wonderful digital photo manager and editor. Learning Digikam also means learning digital photography editing techniques, terminology, and concepts. Using Gnucash or KMyMoney? Same thing-- you have to understand certain accounting conventions and terminology. Writing these kinds of howtos is a lot of work. The fine folks at the Gnucash, Digikam, and Audacity projects all try hard to supply this type of documentation.