Re. Documentation types -- what are the possibilities?

Subject: Re. Documentation types -- what are the possibilities?
From: "Geoff Hart" <geoff-h -at- mtl -dot- feric -dot- ca>
To: TECHWR-L -at- lists -dot- raycomm -dot- com
Date: Wed, 3 Nov 1999 09:49:56 -0500

Bobbie Dofflemyer is in the process of <<...developing a
documentation strategy for a suite of products... What types of
documentation/media do you use to present information and how
do you choose the most appropriate method?>>

We use the standard mix of online and print documentation; if
resources permitted, we might add online tutorials or interactive
wizards, but that's not in the cards anytime soon. (We develop
software as a secondary goal, not our primary raison d'etre.) So I
start with the philosophy that users should have the basics they
need to get started with a product in print (i.e., an overview of how
things work, the metaphor used in the application, a brief tutorial, a
glossary of key terms), and put the primarily context-sensitive
reference material online. I'd prefer to work more closely with the
users of the product to find out what they want, but that's rarely
possible; instead, I get feedback from the guys who actually deliver
the product to customers and work with the customers. See if you
can do a better job of talking to your audience than I do!

<<If I have a complex product that I need to document -- one that
involves a specific methodology and some fairly elaborate
processes in addition to the interface-driven procedures -- where do
I put the different types of information?>>

Sounds to me like the users really need a comprehensive overview
that explains what all the components are and how they fit
together. Using this as your starting point, you can provide high-
level information on which component they should start with for
certain tasks, and how (and when and why) to move from that
component to another to accomplish typical tasks. The details of
the tasks can be set in their own chapters or even their own
manuals if the application is sufficiently complex. Better yet, you
can turn them into "user support" materials and integrate them in
the interface, either directly (as affordances) or indirectly (as
context-sensitive help).

<<Do I provide some sort of tutorial or demo that illustrates the

Tutorials are very helpful, particularly if you can put them online so
they show what happens rather than describing it; that frees up the
user to sit back and watch what's going on, and "learn by doing"
rather than bouncing back and forth between a printed tutorial and
whatever's happening onscreen. But tutorials of that sort aren't
necessarily easy to write well; you may need a bit of training, and
some quality time with the users to find out what works for them.

<<Do I ditch the user's manual altogether (managment's
suggestion for less printed documentation) and develop an online
document that can provide the same information?>>

Nope. I'm still the voice in the wilderness who considers "online
help" to be an oxymoron. Until both the tools and the writers skills
improve, putting docs online is primarily a way to save printing
costs and transfer them to your customers.

<<what do you consider to be a good mix of documentation?>>

Doesn't much matter what _I_ consider to be a good mix. What do
your customers consider to be a good mix? If you can't ask them
directly to find out, start by sitting yourself down in front of the
computer, playing dumb ("I'm not really a tech writer who knows
this software from top to bottom"), and asking yourself: "What do I
do now?" The answer gives you a decent idea of what to do: it may
be "I want an overview so I know where to start" or "I want a wizard
that walks me through this process" or something else entirely.

<<Also, how do you meet the mandate for more online
documentation when you truly feel that the information is best
presented in hard copy?>>

"Kobyashi Maru"! (That is, you cheat. <g>) Anything you can put
on paper, you can also put online. So you move most of the
context-sensitive stuff online, where it's most useful, and add in the
high-level overviews you've provided on paper, and voila: you've met
the mandate for more online docs. But you've also kept the
important high-level stuff on paper for those who need printed

--Geoff Hart @8^{)} geoff-h -at- mtl -dot- feric -dot- ca (Pointe-Claire, Quebec)
"If you can't explain it to an 8-year-old, you don't understand it"--Albert Einstein

Previous by Author: Smaller PDF files?
Next by Author: Trademarks in online help?
Previous by Thread: What goes in a run book?
Next by Thread: Re: Re. Documentation types -- what are the possibilities?

What this post helpful? Share it with friends and colleagues:

Sponsored Ads

Sponsored Ads