A lot of what throws Linux users off appears to be this idea that the documentation is elusive, unwieldy, and not really tuned for end-users to digest. Our cable modem was down for a while, and I was too lazy to get up from my Linux laptop, so I started going through man pages - specifically, from the point of view of a brand new command line user.

ardekantur@gabriel:~$ help

This in itself generates a help page from bash, which is chock full of syntax, builtin functions, small usage statements, and a mention of the man and info pages, as well as a reminder to ‘Use man -k to find out more about commands not in this list.’ While this sort of thing is useful for someone who needs a quick reference for shell scripting, it’s not very useful for a) lost users or b) users who want to learn how to become powerful shell users but don’t know where to begin. I followed the next logical step, trying what the help page suggested, with ‘man -k’. Again acting as if I didn’t have a clue what I was doing, I simply ran that.

ardekantur@gabriel:~$ man -k apropos what?

This… is horrible. From every single standpoint. I know what apropos means, both in regards to its definition and its context on the command line. If you know only 50% or 0% of this knowledge, you’re stuck again. Apropos what? What is the computer asking me? Is this a dirty joke? Homosays what?

I’m considering two things over the course of this little trip through the command line.

1. If a user is lost on their Linux machine, and they’re connected to the Internet on another computer, they’re pretty much saved. If they can Google it, they don’t need to wade through mountains of documentation. I am of the opinion that the documentation that comes with Linux software, through whatever package management mechanism, needs to be in plain sight, easily accessible, and separates the hardcore usage information from what people need to just get going with the software.
2. Since man pages, info pages and the like are fairly well grounded in Linux/Unix history, it may be a mistake to try and alter the core purpose of them. Instead of making drastic changes to ancient documentation, it may be better to offer another kind of documentation at the command line for programs. Man, Info, and Guide. Something like that. This could be on the individual developers, or it could be a completely separate program that synchronizes its local database with a central server of documentation, checking to see what’s installed and what’s not, and what documentation it needs to grab. The server could be duplicated on distro install CDs, and run immediately after installation to synchronize everything up from the install medium on the off chance the user doesn’t have a working Internet connection. So what would be in the Guide documentation? Example usage, how to do common tasks, hyperlinks to more information on the internet, and sample configurations.

I’m not even sure that would be good enough, however. I think what I’m getting at is this: While it’s important that Linux gains mindshare for consumers and end-users, it’s even more important that they take advantage of its power instead of just its price and graphical environments. And if a user gets bored with Gnome and decides to open up the command prompt, I want them to be able to go from knowing nothing about it, to basic functionality and tips, without having to leave that command prompt. It’s extremely difficult to even think of that kind of mindset, though:

A user opens the command prompt. Say they want to list their files. How will they know that the ls command does this? Better yet, do they actually know how their data is stored, i.e. as files? Better yet, how do they know that you can actually do this with the command line? So the observation becomes at this point: instead of simply providing documentation for newbies to the command line, we also need a way to convince them that the command line is something they would be better off knowing. To them, it’s a completely different interface, and much like Apple had to create tutorials and training manuals for the graphical desktop, the Linux community would benefit greatly from presenting the command line to people in a way that showcases its power, instead of just a set of man pages.