|
Clarke sent me a copy of an e-mail months, perhaps years, ago as a
topic for a possible column. I filed it in my "Future Columns" folder and
have taken it out several times, but never quite found what to do with
it.
To be frank, as a Technical Writer for a software company, the topic,
"Bad Manuals" hit too close to home. Although I never here mentioned the
name of the company I worked for (and never will), I still felt that describing
the obstacles it presents to successful documentation would be in part
blaming the company for its shortcomings. I was too happy with my job to
do that.
Things changed a few weeks ago. One day my supervisor, who also supervises
the programmers, told me (in front of the Chief Operations Officer) that
no matter how good a job I did, he still had no use for systems documentation.
That was about three weeks before he selected me to be one of the victims
of our parent company's latest downsizing effort. This leaves the company
without a documentation department (a department that once boasted 8 employees)
and me, of course, without a job.
Since the company no longer requires my loyalty, I can answer the charges
in the letter without feeling that I'm biting the hand that feeds me.
I liked the letter because it was obviously written at a time when the
user was frustrated and needed to find answers, and all he did was find
more problems. I didn't know how to deal with the seeming inconsistencies
in the letter, at once railing at manual creators for insufficient information,
then lambasting their attempts to show their "great knowledge" and decrying
the need for online help systems.
What the user should probably have asked is: "Why don't programmers
make their software so transparent that there is no need for manuals; then
I would have no need for the mediocre documentation that I have to put
up with." Unfortunately, even the most elegantly-written software requires
documentation if it has any level of complexity. Thus, documentation is
a necessary evil.
In the letter, which follows, I have highlighted areas of the letter
to which I plan to respond. My comments appear after the letter:
| I'm an ex-teacher, nine years of college, author of two text books,
about 14 years with the computer, and one who speaks for the many unhappy
people that struggle with manuals that purport to help one cope successfully
with a particular piece of software.
I'd like to have the hours back that I have tried to figure out why
authors, et al, seemingly refuse to do something to make dramatic improvements
in their manuals. There's a kind of arrogance that pervades the
whole formal education system. The teachers, authors don't seem to realize
that all too often they're not communicating; more to the point there's
not enough student-testing. Proof: the extensive Help programs in their
software. I wonder how many users read the FAQ, when they want answers
NOW.
The irony of the prevailing attitude is that the computer is a DO machine
so why the tons of reading the user must put up with before he can DO?
Why
does the system continue to ignore "We learn by Doing?" Regardless
of one's expertise, the bottom line is that one hits a key or a combination
thereof.
It would seem that authors are more interested in showing off
their great knowledge than in communicating with users.
Underlying the problem is the fact that unlike most callings, the formal
system ignores what makes most all other callings successful, superior
people–superior teachers who have proven their ability to turn out
successful students. These are the people that should be running the show,
writing textbooks/manuals, working together to develop presentations
that are almost scientific in nature. Contrast this with what purports
to be intelligent behavior — one's success in the formal system is based
on years on the job, and the amount of one's schooling/degrees. Opportunity
to achieve the rewards common to most callings, those that would draw top
people into the system, is virtually non-existent.
More to the point is the software itself, that which, in my opinion,
is going to revolutionize schooling for, unlike manuals/textbooks it has
the possibility of being two-way communication; it has the potential of
dealing with the problems as they develop. One learns by Doing, starting
from the most basic step, moving on to the next, and being corrected when
he makes mistake. The software would provide for a review of the step.
Ideally, when one has a problem, he could get almost immediate help via
a modem. Modifying future editions of the software would correct the problem
of why users didn't understand.
In sum, the problem is not lack of expertise, it's WHY don't they
get off their arrogant horse to do something about their average to mediocre
communicating?
J. A., San Clemente, CA |
| Why do authors refuse to make dramatic improvements
in their manuals? |
 |
Often poor documentation comes not from refusal to improve, but inability
to improve. I can list from personal experience several reasons for this
inability:
-
Lack of clear standards and specifications for documentation.
-
Equipment that is too limited to handle the robust software needed to develop
documentation.
-
No specifications or sketchy specifications for the software features being
developed.
-
Little or no access to the software as it is being developed.
-
Little or no access to the databases that drive the software.
-
Little or no time allowed at the end of the development cycle to document
features added or changed at the last minute.
-
Developers' failure to inform documentation when the software did not conform
to the original specifications.
|
| Why does the system ignore "We Learn By Doing?" |
|
I'm all in favor of We Learn By Doing. People who have read
this column regularly know that my primary computer learning principle
is We learn by doing it wrong. However, sometimes we don't have
time to learn this way. That is why we have manuals. Even better would
be tutorials, but with the time allotted most documentation people, a time-intensive
activity such as creating an online tutorial is out of the question, even
if the required development software were available. |
| It would seem that authors are more interested in showing
off their great knowledge than in communicating with users. |
|
What should the author show if not their great knowledge? I don't think
"Hi. How are you?" is an appropriate communication form for a manual. What
I think the author really meant to say was that the language in the manual
he was reading was so pompous and overblown ("the explanation and description
of the functionality of this module can be accessed via the xmit button
on the blah blah blah...") that he couldn't cull any meaning from it. Point
well taken. |
| Superior teachers who have proven their ability to turn
out successful students. These are the people that should be running the
show, writing textbooks/manuals. |
|
Here I beg to differ. I have worked with some wonderful teachers and
trainers, especially at my last position. However, their extensive ability
with the spoken word does not necessarily translate to a written medium.
They often make mistakes in written grammar, tend to be verbose, fail to
properly organize the material and lack the technical knowledge required
to use the software that formats printed documents and creates online help
systems or HTML pages. |
| WHY don't they get off their arrogant horse to do something
about their average to mediocre communicating? |
|
I couldn't agree more. Average to mediocre communicating has no place
in documentation. When companies realize that they will stop hiring people
who can type when they need people who can write, and are willing to pay
the difference between the two. |
As for the author of this letter, he might want to evaluate the not-average,
not-mediocre, but poor communicating he does in this letter and revise
it to say what he really means.
|
