Re: How to Publish a Great User Manual

["Susan W. Gallagher" <sgallagher -at- EXPERSOFT -dot- COM>]

Derek looked at http://www.asktog.com/ and commented:
>
<snip>
>I only wish I could put the advice to some use, though. To be able to write
>task-oriented manuals you first need to have a task-oriented customer.

and

>The scorn poured on manufacturers whose web sites are full of 'brochureware'
>(they scan their brochure and have it converted to HTML + GIFs - and are
>proud of it!) is justified but that work provides a good part of my income.
>How am I going to convince my customers that it is a dumb idea?

I've been thinking about this post for a whole day now and I've decided
that yes, it's time to throw my two cents in -- and Derek, please don't
look on this post as disparaging in any way! And yes, I know I'm a
corporate captive and you (by the sounds of it) are a contractor, but
I have friends who contract and we all face the same problems.

<soapbox>
When you approach a client, whether it's a contracting client or a team
within the company that employs you, you are the expert in information
presentation. And while some clients seem to know what they want in
terms of paper-based information, most that I've met don't have a clue
about online information presentation. It's our job to advise them.

Perhaps you could begin by asking your clients to define their goals --
what they want to get out of the products you produce. You may find that
their goals are in direct contradiction to what they say the want but
that they don't know how to express simple, task-oriented instructions
to achieve those goals. Remember -- you are the communications expert
here.

As far as product documentation is concerned, I've never met a client
or employer yet who hired a writer, handed them an outline, and told
them to just fill it in. When you develop your doc plan and outline,
take a task-oriented approach. If your client questions your judgement,
back it up with research -- Bruce Tognazzini's web site, STC journals...
Explain how the approach will impact their bottom (financial) line by
cutting down on support calls...

As for Web pages that are just electronic brochures -- I think our
clients especially need our help to make sense of this whole internet
"thing". Most civilians are completely lost -- they just know that
they need to be on the Web and they try taking the same approach
that's always worked on paper. Again, make suggestions based on their
stated goals. ("Y'know, it we put a list of distributors up on the
Web, customers will be able to buy your products more quickly!)
Again, back up your suggestions with research (www.useit.com comes
to mind) and explain how the approach will impact their bottom line.

(And when you get them to state their goals, remember, just being *on*
the Web isn't a really a goal. Guide them into expecting some sort of
result, whether it's increased sales, better technical support...
whatever.)

No, I certainly don't think you'll bat 1000 with this approach, but
you'll make *some* in-roads. And if you don't at least *try*, you do
a disservice to yourself, your profession, and your collegues. You're
a technical writer, not a typist! Strut your stuff! Share your
expertise! Let your clients see the value they get for the money they
pay you! If you really want to write the next great user manual or
the best little Web site on the Internet, keep pushing the idea until
somebody lets you! It never hurts to ask, y'know!
</soapbox>

<whew!> Okay. I'll go sit down now. ;-)



-Sue Gallagher               http://pw1.netcom.com/~gscale/susanwg/
sgallagher -at- expersoft -dot- com     http://www.expersoft.com

The _Guide_ is definitive.
Reality is frequently inaccurate.  --Douglas Adams


 From ??? -at- ??? Sun Jan 00 00:00:00 0000=