Hazards of Poorly Written Technical Documentation
© Ugur Akinci
I don’t like to whine and 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 earth such “guides” that do not guide, but I don’t know how.
All the best! Ugur
P.S. 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 into a lose-lose one.
