April 26, 2019

Linux Bug #1: Bad Documentation (part 2) - page 2

The Many Faces of Documentation

  • November 19, 2009
  • By Carla Schroder


Troubleshooting is sadly neglected in much documentation. No log files, no error messages, unhelpful error messages, what the heck is the poor user supposed to do? No way to get useful information for getting help, filing a bug report, or writing a patch-- what good is that? (A related grump is message and error windows that are not copy-able-- get a grip, devs, this is 2009 and everything should be copy-able. Saves time and errors.) Some basic troubleshooting tips and resolving common problems are wonderful things.

Community Documentation

"Community" documentation and FAQs fill a useful niche, if someone takes the trouble to collect and organize them in a single location, and makes it all nicely indexed and searchable. It's a lot less work than writing it, and it gives devs a good place to steer users with questions.

Random, disorganized Wikis and FAQs are better than nothing, but not much. Telling users to search mailing lists and forums is about the same as telling them to get lost. If it's a common question then put it in a FAQ. That's why it's called "Frequently Asked Questions." Oh, and don't forget to include the answers.

Community documentation shines when users share tips and tricks, and document edge cases and less-common problems, like conflicts with particular hardware, distros, and other applications. And for helping to figure out if a problem is a bug or something the user can fix.


I am partial to good-quality howto books. Twenty or thirty bucks for a good book is cheap compared to the value of my time and stress levels, and used books are kinder to the wallet. (Though not kind to authors' bank accounts.) Books don't need special machines to read them and won't vanish when Amazon decides you shouldn't have them anymore. They don't need power, nor even for light to read them if you have any handy flammable materials. You can scribble notes in them.

I think more FOSS projects should take advantage of howto books written for their software. Cooperate with the author and publisher, get some free books, and put affiliate links on project pages to generate some income from book sales.

Users Do Read Documentation

I am deaf to the complaints of "users don't read documentation, so why bother writing it." Users do read it, when they can find it. Documentation writers (like me) expand and improve on it. Users become contributors when there are reasonable on-ramps into a project. Fedora and Red Hat represent the gold standards in distro documentation, with detailed, timely, easy-to-find release notes. Red Hat's manuals are wonderful, if too skewed towards graphical system administration for my liking, and all are available for free online.

Tips for Users

Next week in Part 3 I'll review some tips and tricks for the lost, bewildered Linux user seeking answers.

Carla Schroder is the author of the Linux Cookbook and the Linux Networking Cookbook (O'Reilly Media), the upcoming "Building a Digital Sound Studio with Audacity" (NoStarch Press), a lifelong book lover, and the managing editor of LinuxPlanet and Linux Today.

Most Popular LinuxPlanet Stories