Two-track documentation?

Subject: Two-track documentation?
From: "Geoff Hart" <geoff-h -at- mtl -dot- feric -dot- ca>
To: TECHWR-L -at- lists -dot- raycomm -dot- com
Date: Fri, 10 Dec 1999 14:45:32 -0500

Joanne Meehl wonders <<... what happens when the book is a
reference guide that will be used by two audiences? The groups are
software developers, and network administrators/office
managers/anyone else.>>

In most situations, there's one primary audience, and the task then
becomes one of identifying that audience and optimizing the docs
to meet their needs. In most cases, you can still meet the needs of
your secondary audience easily enough (e.g., by putting in
marginal notes, cross-references to more detailed information, and
so on). Sometimes the solution comes from detecting a difference
in the way the two audiences work with the product; for example,
the programmers may shun the printed docs and work solely with
an online reference manual, whereas the office managers stick
strictly to the book. (That's a stereotype, and dangerous for that
reason, but it fits well with the anecdotal evidence I've collected
here on techwr-l and elsewhere. Does your audience fit the
stereotype, or not?)

Where both audiences are equally large and important, you'll often
find that there are areas of little or no overlap between them; for
example, if you've picked the right names for the two jobs, an office
manager and a programmer are highly unlikely to be doing similar
tasks. (The office manager might need to reboot the server; the
programmer might need to reboot it in a variety of nonstandard
configurations for troubleshooting or optimisation. So you'd provide
"general rebooting" info. at the start of the chapter, which will solve
the needs of everyone, and provide a cross-reference to the myriad
options available to power users that you present later in the
chapter.) If there's absolutely no overlap, you can handle these
areas separately; for example, it's common to see an
"administrator's guide" paired with a separate "user's guide" in a
documentation package. In contrast, the areas that overlap
strongly often represent identical needs for both audiences, and
thus don't require separate approaches.

These are all generalities, because without having the details of
your product handy, it's hard to provide more specific advice. But if
you think over what I've suggested in the context of your specific
project, you should find some helpful suggestions that point you to
your own solution.

<<did you just let the reader find their way on their own?>>

Never. One of our responsibilities is to figure out an approach that
guides users efficiently through their tasks, whether those tasks be
simple rote repetition of steps or actual "higher" learning. That's not
to say you should actively prevent users from finding their own way
to knowledge... but you should never abandon your responsibility to
provide help to those who need it.

--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: Decomposing?
Next by Author: When/how is help used?
Previous by Thread: Font Weirdness--Thank you, that's enough
Next by Thread: Cost-of-living increase in US this year?

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

Sponsored Ads