How NOT to Write a User Guide
I don’t like to be negative in general. Life is too short to go around fuming about things that we can’t change.
However, there are times when we all need to be critical in order to improve things; especially if they fall within our area of expertise.
The other day I bought an iPhone docking station for my kitchen, the kind that helps you listen to music via iPhone.
The unit is perfect. I have no complaints about it. It was money well spent.
Yet, the morning after I bought it, I woke up with this insistent alarm winding its way from the kitchen. I got up and stumbled my way to find the source of the irritation. Yes, it was the new docking station I bought. Its alarm went off. I turned it off and went back to bed again.
Later in the day, I remembered: I turned off the alarm but I did not DISARM it. Which meant, it would go off again the next morning.
So I had to disarm the unit. But how?
Just looking at the unit did not suggest much. I found out how to display an alarm icon on its LED screen and played around with different controls a bit. No dice. The unit was still ARMED.
So, I did what millions of other consumers do when they fail to figure out things on their own: I picked up the USER GUIDE that came with the docking station.
And yes, there it was:
“Review, Arming and Disarming Alarm (Turn Alarm Function ON and OFF)”
Leaving aside the vexing issue of the heading’s non-parallel construction, I proceeded to read the instructions that would help me from waking up early the next morning:
“To review the current alarm time and arm the alarm or to disarm the alarm, just press the ALARM BUTTON as needed. If the alarm is armed, the alarm icon and current alarm settings appear.”
That was all. That’s exactly how the section read. Just two sentences and not a word more.
If any of my students turned in an assignment like this they’d fail. Yet, they printed this nonsense and expected consumers like me to learn how to disarm the product by reading and following the instructions. What can I say…
I got in touch with the company. The response from technical support was polite and timely but the official had no idea what I was talking about. She insisted the description was very clear and I should be able to disarm their product by pushing the alarm button “as needed.”
I wrote back to her:
” I’m disappointed that you think the user guide description is sufficient and correct. Please look carefully at what the user guide says:
“To (1) review the current alarm time and (2) arm the alarm or to (3) disarm the alarm…”
As you can see there are THREE very DIFFERENT TASKS mentioned here. REVIEWING the current alarm time is not the same as ARMING the alarm clock, nor is it the same as DISARMING the alarm clock.
And to accomplish all three (!) I should “just press the Alarm Button as needed”? What is the operational definition of “as needed”?
Do I “need” to press the button once to REVIEW, ARM, or DISARM the alarm? How is that possible at all? It does not even make sense.
Or do I “need” to press TWO or THREE times “as needed” to REVIEW, ARM, or DISARM the alarm?
I do not see how you can you think that this poorly written user guide is sufficient to show the users how to DISARM the alarm clock.”
Result: I’m still waiting for a response.
What do you think dear reader? Am I missing something here?
I wish I could evaporate from the earth such “guides” that do not guide, but I don’t know just how.
I would say documentation was an after thought and a necessary evil maybe for the product developers. It had to be somehow packaged with the product and they did it. Who cares for task analysis or impersonating user behavior?
To me, part of the problem is they decided to put multiple instructions in a single step – which rarely works – instead of three distinct steps (one for REVIEW, one for ARMING, and one for DISARMING). At the very least, it should have been three separate steps, with an additional section describing the icons.
As someone who has worked in localization and have had significant amounts of material translated, I’m wondering if this was a word count issue. Maybe I’m over reaching a little, but knowing the cost of translation, it wouldn’t surprise me.
All that being said, it still is no excuse for poorly written instruction.
The sad irony is, these companies commission, print and distribute these poorly written documents; and then, they turn around to tech writers and tell them “nobody reads these manuals anyway” when negotiating a project. They are not aware that they’re helping create a self-fulfilling prophecy while generating a bad user-experience for no good reason at all. They debase what can be a win-win relationship to a lose-lose one.
I think the instructions were confusing to say the least. What’s more, I have to wonder about the usability testing that went into the product itself in the first place. If it’s that hard to figure out, maybe the technical writers didn’t understand the problem either, and there was no way to make up for a product deficiency in the instructions.
I agree with you to a degree, Bill. There’s nothing worse as a consumer than buying a product with major usability flaws, however, I believe if these writers spent enough time driving the product in a lab environment they would have been able to come up with more effective instructions.
As technical communicators we’re taught to be able to write about a product we have to spend time using and learning the product. I think maybe this feature got overlooked somehow.