TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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-
