Writing Technical Documents for Computer Beginners
Grokdoc
I asked a professional technical writer, to write about what would make this project really useful. Here is his response:
WRITING TECHNICAL DOCUMENTS FOR COMPUTER BEGINNERS
~by Nicolas Richards
The first rule of writing technical documents is to know your audience. This means more than a mental acknowledgement of who you are writing for, and then plowing ahead in your usual style. It means crafting your words to suit your audience, even if your audience thinks in wildly different ways from the way you think. Consider the plight of the help desk. The person manning the phone knows quite a bit about software and hardware, but the person calling in may not. How many times has a problem been reported to a help desk that couldn’t be solved until the person taking the call dialed down the probable causes to a level commensurate with that of the caller. “Is the monitor plugged in? No? Ah, well plug it in now. Is it in? It works now? Wonderful. You’re very welcome.”
This can be the hardest part about writing for the total computer beginner. You and I are light years ahead of them. Think about when you first learned to drive a car. What happened when you had to come to a stop at a stop sign? Didn’t you concentrate, trying to make sure you applied the brake just right so as not to stop short or to overshoot the intersection? Now that you are experienced, however, how do you approach a stop sign today? With one hand on the wheel, looking at your friend in the back seat, twiddling the radio buttons to find a better song, and noticing your hair is messy in the mirror. And what do you know? You come to a stop better than you did when you were first starting out. What changed? You developed muscle memory. Your body can automatically handle the instructions to the foot and to your steering hand while barely taxing the brain. There are so many steps that you used to laboriously take manually to make sure you came to the stop correctly that you now take for granted. Why, you don’t even realize you are taking those steps, they’ve become so automatic.
It’s the same with software. You don’t even think about clicking versus double-clicking, or moving one window in front of the other, or expanding a window, or minimizing it. You just do it while thinking of a hundred other more interesting things. It’s part of your hand’s muscle memory now, not worth thinking about. Guess what? The beginner has still got her tongue sticking out the side of her mouth from concentrating so hard to not make a mistake. You’re sailing into the stop sign, the beginner is running steps through her head.
That’s why it’s so critical to know, and I mean really know, your audience. In our case, our audience is made up primarily of those rank beginners who think the computer is going to blow up if they press a key wrong. All right, maybe not that basic, but for a certainty there will be some of those coming along for the ride too. The “which key is the Any key?” crowd.
This is why Grokdoc is unique and not covered elsewhere. Most Linux documentation, even those aimed at beginners, is written with certain technical assumptions in mind. Assumptions that might work for many users, but it will leave out the total beginners. Microsoft has spent millions of dollars to do usability studies aimed at trying to understand how such beginners react when they sit down at a keyboard. That’s valuable knowledge for there is no other way to really know what is going to happen than to observe it in action.
Have you ever taken part in a usability study? I did once as a beta tester for the original Prodigy online service back when IBM was designing it. I was paid to come in to a local IBM office, sit down at a special computer, and given a set of specific tasks to accomplish that day on Prodigy. Video cameras captured everything I did. If I tabbed to a text box and then realized I missed a step and tabbed back, the camera caught it. If I was asked a question on the screen and it took me a while to figure out what answer I should give, or even how to answer such a question, the camera caught my pause. If I circled back to a screen I had already filled out because I didn’t know where I was going, they caught that too. There was no one next to me telling me what to do. I was on my own with the software and they wanted to see how I would cope.
That is the only way to know if the software is ready for beginner prime time. If the beginner smashes his head against the keyboard in frustration, it’s time for the software designers to get back to work. Remember, the software makes perfect sense to the designer and the programmer, for they know it inside out, and it’s their baby. Even those of us who have not programmed FOSS can still feel that sense of ownership over a set of software we have come to have affection for. I can tell you from experience that it is painful as a programmer to realize the user cannot figure out how to use your software. You get defensive and make excuses, but there are no excuses. Yes, there are dumb users out there, but get used to it. It’s humanity – including the dumb ones. Dumb ones get to use software too, and we need to help them learn.
It is very valuable to have this sort of usability testing done, but it costs money. Lots of money. We don’t have that kind of money, so we have to apply the “many eyes” principle to compensate. With the many volunteers on Grokdoc, we can make up for the lack of financial resources by volunteering our time to help make FOSS better, even for the dumb ones. How do we accomplish this? By replicating the usability testing experience, but by one-on-one encounters.
Take someone who is new to Linux, or even new to computers in general, and explain how they can help this project. Ask them to sit down with you at the computer while you have them try to accomplish a predetermined set of tasks with that software while you watch. Then let them do it. You just watch. Take notes while they try to accomplish each step. See when they make a wrong move – why were they led astray at that moment? What kept them from leaping to the correct step? Is there any way the software could be designed to make the correct step more obvious, or the incorrect step less enticing? If they come to a dead halt, unable to figure out what to do next, make a note of that and why it happened. Ask them questions to see what they think they should do, and why nothing in front of them appears to be the correct step in their minds. Then help them figure out the correct step and stand back again while they continue.
The thing that will tempt you more than anything else at this point is the terrible urge to jump in and tell them, “No, do this instead,” just to ease the excruciation of watching them take forever to come to the right conclusion. Fight that urge! You will think to yourself, “Ugh, it’s just a stop sign! It’s so simple!” Meanwhile they are thinking to themselves, “Oh no, a stop sign! What do I do?” You need to let them struggle with it on their own, for it is in their struggling that you begin to get insights into what could be changed to make them not have to struggle with this step. If you just tell them what to do, you short-circuit the process as surely as if you took the steering wheel out of their hand and stomped on the brake.
As hundreds of volunteers use this method with computer beginners trying various software packages, we can build up a usability library that will prove invaluable in helping to make FOSS appealing and inviting to the average Windows user and the total computer neophyte. You know, that 90% of the market whom we want to try Linux. This will go a long way toward making that dream a reality.
