A Suggestion: A Groklaw Documentation Project

by Pamela Jones
Groklaw

April 16 2004

If it had not been for Mandrake, I probably would have given up on GNU/Linux years ago when I was starting out, but they made it so easy, I could use the software while I learned command lines. I'm still learning, actually, in part because Mandrake makes it so easy, you hardly ever need command lines. This is both good and bad.

When I read about the world switching to GNU/Linux, I get a worrying ache in my stomach that maybe some of them will have a hard time finding their way around. I know from personal experience that you can easily do the normal, everyday things in a distro like Mandrake. I wouldn't hesitate to install it for my mom, and if she weren't so set in her ways, I would. She'd like it just fine. But if anything went wrong, she'd get lost, I think. Or if she got adventurous and wanted to try something a bit off the beaten path, what would she do?

I'll give you an example. Recently we wanted to check to see if Caldera distributed the ABI files without the supposedly necessary copyright notices from the BSDi settlement. Some of us, including me, didn't know how to find out. Now it should never happen that if you want to do something, you can't unless you know someone who will explain it to you personally.

I had Midnight Commander on my computer, because I had installed it meaning to check it out some time, and I vaguely knew it could help, but I didn't know exactly how. The man pages were not helping and without Dr Stupid's handholding, I would not have had a clue how to find those files. It took a while to even find mc, because Mandrake doesn't put things in the menu that are off the beaten path. You can make it happen, but they don't tell you that unless you dig around and figure it out. Such things should be the first thing they tell you, in my opinion. There is decent documentation, but for newbies there aren't enough words. They don't want to dig around and figure things out.

Now, a lot of you will say to check the man pages. A lot of the man pages are useless to a newbie. They list the command options but they don't explain what they do or how to implement them or which one helps with your current problem. Every man page should open with examples, showing how exactly to type in what you want, depending on what you want to do. If there is one such book that is so good it does what I need, please say so, but I've never found one. I have found one book that helps me more than others, but it's basically designed for Red Hat systems, and that doesn't always help on a Mandrake setup. Isn't it possible to have a book that anyone could use, including everything a basic user needs?

I thought of this for a couple of reasons. First, my dear old Dell, which has Windows 98 still on it for some work functions, couldn't find the modem the other day. I realized it because I put in my trusty Knoppix and *it* couldn't connect to the internet. So I knew the problem was real, not just a Windows confusion. I worked and worked at it, steadily trying to rule out this and that, and I couldn't get the thing to work. I even tried in Windows, thinking I might find a clue. That's when the light bulb finally went off. Realizing that when you hit a wall, you have to think from the basics up, I went to check if the telephone line was plugged in, and it wasn't.

Now, aside from revealing my own inadequacies, the point of the story is, my mom would simply never even think of that. If there was a book she could pick up that would say, "Did you check to make sure the telephone line is plugged in?" with a picture showing what a telephone line looks like and how you know where to plug it in, it would make all the difference. Ideally, it should be built into the computer, so she doesn't normally need a book, but a book is also essential, because if your computer is dead, you need the paper book in your hand to rescue yourself.

This article [ http://www.citizenlab.org/opensource/ ] someone sent me goes into the issue with a bit more depth, for those who like to think deeply, and it's what made me think of this today. But here is my thought. Groklaw is ideally suited to doing something like this, don't you think?

Now, I know nobody wants to write that stuff. It's boring on its face, unless you are writing for someone you love and care about, but if the world is switching to GNU/Linux, and they are, maybe it is time to start to seriously care about that? Some tasks that are boring on your own are more fun if you do them with a group. I think that's the principal behind quilting bees or washing your clothes at the river all on the same day. I think a project like this could actually be fun, if we did it as a group project.

The gang's all here. If the heart is too, it would be mighty easy to collect the necessary info, topically, and I like to write, so I could jazz it up a bit, and shazaam, it'd be done without being a headache for any one person or small group. There are no space limits on the Internet, so it could be as extensive as we like or need it to be. I don't like to impose ideas, so I'm just throwing it out there to see if there is any interest, or more accurately enough interest, in doing a project like that.

The first step would be to decide what topics should be covered, topics that would apply to any distribution. We can do that, because we have readers using lots of distros, so we could easily include things like "but in Debian, it's a little different", etc. A lot of the effort would be to collect available information and then just make it better. Or if we find something that really is perfect, asking if we can include it with credit or alternatively provide a link to it. Some would be our own experiences. Better yet, let's all sit our moms or Windows friends down in front of a GNU/Linux box and notice what happens. What do they say they'd like? What makes them hit a wall? Corporations hire experts to do exactly such things. We don't have money to do that, but we have people galore. We could do a really good job at this.

My personal choice for a first project would be to create a little handbook on Knoppix, including how to install it on your computer, if you decide you want to. I sent Knoppix to a journalist the other day, and I wished I had a friendly little how-to handbook I could send along with it. What do you think?

07:04 AM EDT

Copyright 2004 http://www.groklaw.net/ - http://creativecommons.org/licenses/by-nc-nd/3.0/