Re: Making Manuals User Friendlier

[Jane Bergen <janeb -at- ANSWERSOFT -dot- COM>]

Bill Sullivan wrote:

> > This is a response to Peter Ring's ringing in on the subject of
> > this list's alleged decline.  He wanted a discussion on how we can
> > make manuals more user friendly.  What's to discuss?  We make
> > manuals friendlier to users when we:
> >
> > 1.  Get to the point.
> > 2.  Tell them what they want and need to know.
> > 3.  Make it easy for them to find what they want and need to know.
> >  4.  Say Good-night Now when we have said enough.

Peter Ring thoughtfully answered:

> Extremely basically, of cause you are right. But have you never
> thought about ... - WHAT they really wanted to know? - HOW you make
> it easy for them to find what they want to know? - WHEN an index is
> needed? 2 pages: very unlikely. 200 pages: certainly!
>   But how about 8 pages? 20 pages? 40 pages?
> - HOW to get to the point, in casu: How to write an instruction? -
> WHO are they really - education, culture, reading ability, ...? -
> HOW MUCH you should write to which people? - IF they can read at all
> - and if yes: how difficult text? - IF you need to make a cartoon
> here - or how cartoon-like? Just to mention a few.

Bravo, Peter. This approach is what differentiates a professional
technical communicator from a person "who can write" ... at least in
my organization and experience. Yet many companies today are
streamlining everything and trying a one-shot approach to writing.
When I first started at this company I asked "Who is the audience?"
and was met with a blank stare. Finally the vice-president said, with
all sincerity, "whoever we can sell it to." I choked.

Eventually we've come around to defining our audience pretty clearly,
but the problem is we are developing  a product that will be used by
two extreme ends: an agent in a call center who may or may not know
how to turn on the PC, and, on the other end, the systems engineers
who maintain the system. Whew! It's a challenge.

We really need to understand the audience or user or reader
....whatever your term .... it's absolutely basic to the questions of
style, tone, and more concretely, using cartoons or indexes or even
page layout.

Unfortunately, the bookstores are full of books about how to make the
pages look pretty, how to avoid passive tense, or where to put
commas. It's much harder to find good books which discuss the issues
of readability, legibility, analyzing readers, etc. When I was
studying tech writing in graduate school we had a few good textbooks,
but the books, articles, etc. all were at least 5-10 years old.
Little is being done now, evidently, which is why this list is so
helpful. We need more studies based on real-world situations. We need
more information on using the tools and technologies available today
to accomplish "making manuals user friendlier" rather than a
simplistic, one-shot approach.

Jane Bergen
...............................................................
 Jane Bergen, Technical Writer
 janeb -at- answersoft -dot- com   or   janeb -at- airmail -dot- net
    "The difference between the right word and the
     almost right word is the difference between lightning
     and the lightning bug" (Mark Twain)
...............................................................