Grokdoc - A Status Report

by Pamela Jones

April 18 2004

The reaction to my suggestion for a documentation project was overwhelmingly positive. I have been deluged with offers to help, including offers from two professional tech writers who do such things for a living. Even negative reactions were helpful in tweaking the idea to advance it while being sensitive to those feelings.

So it's a go. I have obtained the necessary domain name, which will be kept separate from Groklaw, but linked to from here. Groklaw will continue as is, covering SCO and any other attacks on GNU/Linux and with an increasing focus on patents.

I accept the many suggestions that we do Grokdoc as a Wiki. Anyone with lots of experience with wikis, please let me know your willingness to participate and what your skill set is.

Here's the most important piece of the current idea, incorporating the wonderful input I have received:

We apply the open method to doing a GNU/Linux newbie usability study.

No one, to the best of my knowledge, has done this on such a scale. Grokdoc will be written from the results we observe.

We are not trying to duplicate effort. We are trying something brand new. Instead of experts telling newbies how to do things, we will let newbies show and tell us what they need.

As you know, in addition to using GNU/Linux, I also have an iMac. I know Apple did usability studies, and their stuff just works so easily. Hiring experts to do such studies for the free/open world is probably beyond the means of most of the programmers we have. So this is my solution, an open research project, which will lay the foundation for newbie documentation. We have the eyeballs, so it needn't be stressful on any one person, not even me, if we set up as a Wiki. You don't need to be a Groklaw member to participate. Anyone in the world can jump in. That's the beauty of the open approach. Anyone who doesn't feel like doing this doesn't need to. But if you see the power of this idea, the way I do, please do participate. I see the power of the idea because I lived it. I know what newbies need, because I was one, so I can empathize. I also see this is the next hurdle for GNU/Linux adoption, so why not fix it? Microsoft uses ease of use as a selling point. We can fix that too.

So that is the idea so far. Feel free to tweak, suggest, edit. I am very excited about this project, because I know it can work if enough of you help out, and I am confident you will.

Here's my concept for the first step: all of us (and there are nearly 6,000 Groklaw members, not to mention many, many more who visit regularly but don't sign up for a user account but do participate actively) sit down with our mom or dad or any Windows-oriented friend or relative. Let them try to use GNU/Linux, any distro you have on hand, including Knoppix and its cousins.

Don't show them anything. Just watch and record. What do they have problems with? How did they try to resolve the problem? What happened? Did it fix it? If not, suggest they try LDP or Google or the manuals that come with the distro. Watch them try and record the results. What works? What doesn't? If they hit an unmovable wall, then step in and help, but don't leap in until they are about to give up. I do want this to be useful research, but I don't want your mom to hate GNU/Linux either. But let them really try to solve it themselves without input from you until they fail utterly.

Have them try to do a minimum of four things: email, a simple letter, a firewall, and surf the internet. That includes setting up for email and surfing the internet. What do they spontaneously say they like and what do they say upsets them? Is the menu clear? Where do they get lost?

If they express an interest in trying other tasks besides these three, let them try, by all means. Maybe, for example, they want to know how to burn a CD. Or they want to know how to set up the PC to interface with their digital camera. Note what you observe is hard for them to do, as well as the things they verbally express are hard. Of course, we need to know exactly what distro you are using, including version.

If they are willing to try to install a distro, go ahead and let them try. Record what happens.

Answers will vary, but that doesn't matter. Standing back and looking at patterns will be the next step. After they have accomplished all three tasks, write down what solved the issues and what didn't and what you think (or they indicated) would have helped. Clear suggestions would be appreciated and very valuable. Would a screenshot have helped? More words in a manual or online resource? Less words? Better organization? Less technical? In other words, evaluate yourself what you think is needed, and please be very specific and as detailed as you can.

Then, send in your results to Grokdoc's wiki page for that input once it is set up. You will be able to do that anonymously or not, as you choose. There will be a credits page for those who wish to be listed.

We also want input from you on resources that already exist, like LDP. We have a lot sent in already. We will list them on a dedicated page, and hopefully some of you geniuses will figure out a way to index it so it is easily searchable.

Then we will have two versions of Grokdoc, working from the issues that we find crop up the most. The first will be your input, raw and unabridged, which anyone can write to, edit, etc., wiki style. The other will be an official version, incorporating the best ideas and materials, but polished by our tech writers and me, along with others who may wish to help and have the skills.

I want screenshots and graphics too. If you see a way to explain a task that way, by all means send in your complete solution, with graphics, screenshots, whatever, to the public page. If you wish credit, that's absolutely fine. If you don't, that is fine too. Be aware the Wiki will be under a Creative Commons license.

The official version will not be editable by the public. But the public can choose to use whichever version they like best.

Some have suggested a paper manual and a CD, ideally. You need something that you can use when you can't start your computer, they point out, so an online-only document isn't enough. I agree that it is a good idea, but that would require some funding, and I am drawing a blank on that. I suppose we could set up as a nonprofit organization for that project and request funding. I haven't thought through that part completely yet. I just don't know any way to do books and CDs as a volunteer project without funding. The online work we can definitely do.

The reason for having one unchangeable version is because we thereby can take advantage of the professional skills that we have available to us. Also, I have to factor in the troll effect. I have learned from doing Groklaw that trolls try to skew the conversation in negative patterns. I expect a public usability study may attract those with a desire to make GNU/Linux look really, really hard. However, just as I can tell the difference usually between authentic comments and troll nonsense, and so can most of you, I am sure the weeding process will be effective here as well for our Grokdoc.

Meanwhile, as we work out the behind-the-scenes details and get set up, if you wish to talk to me about the project, please email me. Instead of pj at use pamela at the same Sorry to be using code language, so to speak, but I get enough email from Nigerian royal family members and chipper dying persons who do not wish me to feel sorry for them because we all have to die but who would like my money in the interim.

Anyone who wishes to get started with mom or dad or Windows friends, by all means, feel free to start. I'll keep you posted on developments. It'll be fun, and besides that, it'll be groundbreaking, and if we do it right, I think the finished product can be genuinely useful.

08:54 AM EDT

Copyright 2004 -