February 21, 2019

Linux Documentation From A User's Viewpoint - page 2

Reading the Fine Manual-- if it Exists

  • December 1, 2009
  • By Emery Fletcher

I bought a copy of Linux In Easy Steps, by Mike McGrath (Computer Step press, Warwickshire, UK, 2008) just because it had a 16-page dictionary of the most common command line symbols and words. It was the first I'd seen that set out in plain language the meaning of each command and gave a brief, very simple illustrative example, just like any good dictionary would. It's not designed to make you expert at constructing command strings, but it is a huge help toward understanding what each string you're told to use really does.

I suspect a similar situation is taking place upstream in the process, where you experts are looking at the source code for things. It may be clear what steps the coder has taken to make his program dance, but why did he do it that way? Is there something in that particular step he inserted that goes beyond what is obvious, or is it just wasted effort? No dictionary will help in that case � it requires documentation, a clear explanation of the intent as well as the content of the code. What's needed is the computer science equivalent of a physics research paper, or at the very least, the abstract of such a paper.

That is no job for English majors, not unless they have an equally strong background in computer science (well, mathematics or physics would probably qualify as well). But in this upstream case, it is sensible to assume that anyone really digging into the code knows a good bit about programming to begin with. It's not necessary to explain at the rudimentary level a newbie could understand, because the newbie is not going to be reading it anyway. Good documentation is something that takes into account both the subject and the audience.

Not Clueless, but Not Confident

For myself, I'm in an audience that might be described as Apprentices, somewhat past the Clueless stage but still far from Confident. I need all the documentation I can find about the ways that programs and dependencies interact, what should be left to the built-in capabilities of high-level programs versus what would respond best to deep command-line tweaking, and where to find the quick-fix methods that fix the most common glitches. In short, I'd be delighted to RTFM if someone would write the FM to read!

Most Popular LinuxPlanet Stories