February 23, 2019

Linux Documentation From A User's Viewpoint

Reading the Fine Manual-- if it Exists

  • December 1, 2009
  • By Emery Fletcher
I'd like to put in my two cents' worth on the matter of documentation. I'm not an expert like Carla Schroder or Bruce Byfield, the two who brought up the topic, but I'm the very sort of person who needs it most, still pretty much of a newbie, but one who learns best by reading. It's a good thing reading is my preferred mode of learning, because as it happens I've not personally met a real live human who is a Linux expert, one who could give me over-the-shoulder instructions as I muddle through.

It occurs to me that there must be a whole lot of people out in the real world who are not unlike me. They have used their PCs long enough that they're familiar with all the processes they usually use, but they suspect there's a lot more stuff they could do if only they knew how. After a few tentative experiments with what they've been using, they learn that the motto of Windows is You Can't Get There From Here.


If you're an absolute newbie, there's really no lack of useful books that will help you along on the Freedom Train to get a Linux box set up with one of the transition distros like Ubuntu or Mepis or Mint, and before very long it becomes as familiar to you as Windows once was. But now and then something comes up, like creating the /home partition you find you should have set up during installation, and the instructions for it involve a good deal of copy-and-paste of scripts.

That's where documentation gets dicey. Sure, you can do as instructed, but that's no different from �click on this, click on that�. It's an instruction, telling you HOW but not WHY. Real documentation should give something more, not necessarily a full account of every detail, but at least an overview of what processes are involved and how they operate. I remember lurking on user forums long before I ever attempted an installation, trying to get some background. I soon learned that there were just a few really helpful gurus who would put their instructions in the form �What you use is (command), and what that does is (operation) on the (target) to make it (result). The way you type that into the terminal is...�

Why and How

Okay, that's pretty ad hoc documentation, but you get the point: it explains the real function of what has been encrypted in the syntax of the command. Commands, after all, are not a verbal language, they're more like mathematics, with functions and variables and operators. The full documentation of a single command line would actually look a lot like the text surrounding an equation in a physics textbook. But a physics textbook is designed to be read by someone deeply committed to learning the subject in detail, a person willing to spend as much time and energy as is needed to understand the meaning completely. A new Linux user isn't hell-bent on a PhD in Computer Science, but she deserves a little more explanation of what some particularly arcane string is actually doing to her computer.

Most Popular LinuxPlanet Stories