Two-track documentation?

["Geoff Hart" <geoff-h -at- mtl -dot- feric -dot- ca>]

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