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:One doc for each user ? From:"Peter Ring, PRC" <prc -at- PIP -dot- DKNET -dot- DK> Date:Thu, 25 Jul 1996 09:29:43 +1
On 24 Jul 1996 Frederic Wronecki <frederic -dot- wronecki -at- WANADOO -dot- FR>
France Telecom, Paris, France, wrote:
> Ideally, a technical document should address one, and only one,
> category of users.
> But there are cases when a significant proportion of the
> information must be simultaneously provided to all the categories.
> It seems then difficult to compel writers (*) to design different
> documents if the common core represents the biggest part of each
> one.
> I'm trying to set up a guideline for this.
> I proposed the following rule : Make one common document if, and
> only if :
> - the common core represents at least three quarters (circa) of the
> document ;
> - AND you can display without any ambiguity (via typographical
> attributes) which blocks of information address which categories of
> users.
> Some colleagues rated this "irrealistic", impossible to implement
> and to check.
> Any experience would be appreciated.
Theoretically, Frederic Wronecki is completely right. And in fact,
that is what a number of companies are trying to do, more or less
successfully. In software a "How to get started" manual for the
beginners and a "Complete reference guide" for the experts is a
good example. In several manuals for some of my clients, I have
used graphic symbols (defined in the "How to read this manual"
chapter) to tell the experts that this stuff is for beginners,
only, and the feedback has been positive.
The major practical problems are:
- To find out who the users are.
- To relate that to the readability index level you must then aim
at.
- To find out how much you can expect the beginners to understand.
- To test if it works.
I have developed a number of useful tools to solve these problems
in practice. In the first hand they were developed for my own use,
and they proved useful. I was then involved in teaching technical
writing, and most of my students accepted my ideas and started
practising them. Last year I wrote a book about the methods, and
although they have been slightly refined since then, I think you
will find a number of useful tools and answers to your questions
here.
You can find more information on the book and some of the tools on
my homepage for user friendly manuals, see below. If you don't
have access to the web, or if you want to by my book, please write
me directly.
Greetings from Denmark
Peter Ring
PRC - specialist in user friendly manuals and quality measurements on
manuals.
prc -at- pip -dot- dknet -dot- dk http://www.pip.dknet.dk/~pip323/index.htm
- homepage on user friendly instruction manuals with tips for
instruction manual writers.
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-
