TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Re: Are manuals and help read? From:Andreas Ramos <andreas -at- NETCOM -dot- COM> Date:Thu, 17 Mar 1994 09:39:31 -0800
An enlightening experience is to do techsupport. At one point, since I
knew the product (having written the manual), I did techsupport for a
while. One has to remember that the customer is always right. Thus one
can say "You stupid idiot" out loud. That's why there is a hold button on
I'm an avid reader. No, I read constantly. I re-edit and rewrite the text
on the back of cereal boxes. Tighten it up, say it better.
It drove me crazy that users wouldn't read their manuals. One puts a
lot of effort into writing a clear, freindly manual, and they won't
even open the thing.
After a while, my techsupport manual got to having certain pages
perpetually "post-it'ed", the same old ten questions. After yet a longer
while, I knew the pages from memory (i'd sit there, with a customer
on the teleophone, with my feet on the desk, looking out of the window,
watching the birds make their nests, and I'd say "okay, paragraph 5:
let's go through that one..." my co-workers were unnerved by this.
I learned several things. Never assume that the reader is following
along. Either they jumped in at page 120 (and haven't even looked at the
previous 119 pages) or they simply don't understand the
technology/program/concepts. I began writing manuals which repeated
themsleves over and over; I figured that the few who do read manuals may
be annoyed at the repetition, but the remainder would be helped. (and
several people did complain: Why do you repeate this , if you already
said it in chap. 3?)
The other thing i learned is that a boring manual (clear, dry, factual)
won't be read. You have to liven it up; you have to make it personal. I
mentiioned Honda car manuals. Only if you are stuck in a parking lot,
waiting for someone, do you read the Honda manual! Honda and Toyota
realized that people don't read their manuals, so they put little lights
on the dashboard which tell you when to change the oil, etc. Since most
users look at manuals only when they have problems (they'll flatter
themselves into thinking that they can use a program without looking at
the manual), I now write mostly troubleshooting; half of the manual is a
tutorial and the rest is a question and answer: "Why is the screen dark?"
"Turn it on." THis format has the advantage that one can be repetitive;
the user will hunt out his/her problem, read the solution, and ignore the
I find that it helps me, when writing a manual, to sit with the tech
support people and talk with them. (and this is a two week affair, not
just a morning). I ask them which are those questions which people ask
over and over, and then I document the hell out of them: explain it REAL
slow and then explain it all over again in the troubleshooting chapter.
The point in a manual for the company is to satisfy the customer.
Manuals are producedby marketing, who 1) wants happy customers 2) doesn't
want complaining customemers. Complaints are either calls to techsupport
or returns for refund (program doesn't work! Yes it does, you're too
stupid to understand it!)
By "proactively" (i hate that word!)(and what about "enhanced
productivity"?:( writing the manual to avoid misunderstandings, one
reduces the calls to techsupport and the returns for refund. This is
the bottom line for managament; they being a bunch of MBA's, who haven't
read a book sinnce "DuckDuck lays an Egg", would have no problems with
not having a manual at all! This is what I meant in a previous e-letter;
we the techwriters like to create manuals because it's an income and it's
a challenge to write clearly. But management is only looking at people who
are expensive and at $50,000 printers' bills. The idea of on-line help is
mostly an American thing; European companies either have a very simple
version or mostly none at all (I produced manuals in Europe for four
years, and have seen or used programs in British, French, German,
Danish, Spanish, and Swedish)(yes, I read all those lanugages, and a few
more). I'm not talking about European versions of American programs,
since these will have the translated on-lin help. I'm talking about
German programs written for Germans.
As we move to CD media for programs, I think we'll se that manuals will
be entirely on disk (easy to update, no warehouse storage, etc). The
techsupport as well will develope more, with 24 hour free (or fee)
techsupport. This will happen as part of the dropping prices for
programs. That which once cost $500 is now selling for $99. Even
Pagemaker 5.0 sells for $250, and this type of program only three years
ago sold for many times that. With falling prices, there will be a
tremendous pressure to reduce costs. Many programs are now sold at $59,
with sixty day refund guarantee.
Andreas Ramos, M.A. Heidelberg Sacramento, California