Re: One doc for each user ?

Subject: Re: One doc for each user ?
From: Robert Plamondon <robert -at- PLAMONDON -dot- COM>
Date: Fri, 26 Jul 1996 11:40:47 PDT

Frederick Wronecki writes:

> Ideally, a technical document should address one, and only one,
> category of users.

I disagree. You're confusing method with goals. The goal is that
all the users willing to consult the documentation get the information
they need with a minimum of effort and error. Writing individual
documents for each category of user MAY address the goal (or may not),
and MAY be more effective than alternate strategies (or may not).

When creating a heap of documents, one for each category of user, consider:

1. Do all the users know which kind of user they are? That is, do you
have razor-sharp distinctions that you and the users themselves will
agree upon? If beginners accidentally look in the User's Guide when
you wanted them to look in the Tutorial, and experts can't find
the information they want in the Technical Reference Manual because
it relates mostly to mere mortals, and is thus in the User's Guide,
who are you serving?

2. Do users progress form one category to the other very quickly? If
a 15-page tutorial serves its purpose in an hour, the 50-page User's
Guide is helpful for a week, and after that the 200-page Reference
Manual is all that ever gets looked at, you really only have one
category of user. It would be best to write a single, integrated,
carefully cross-referenced work, even if you print and bind it as
three books. Having three independent works wouldn't have the
cross-referencing and synergy of a single work.

-- Robert
Robert Plamondon, President/Managing Editor, High-Tech Technical Writing, Inc.
36475 Norton Creek Road * Blodgett * Oregon * 97326
robert -at- plamondon -dot- com * (541) 453-5841 * Fax: (541) 453-4139

TECHWR-L List Information
To send a message about technical communication to 2500+ list readers,
E-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot- Send administrative commands
ALL other questions or problems concerning the list
should go to the listowner, Eric Ray, at ejray -at- ionet -dot- net -dot-

Previous by Author: Re: note taking
Next by Author: Re: Taking notes, once more with feeling
Previous by Thread: One doc for each user ?
Next by Thread: 3.11 Secondary Window Jump?

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

Sponsored Ads