Writing for two or more audiences

[Jean Weber <jean -at- wrevenge -dot- com -dot- au>]

I'm catching up on reading this list, so this contribution is a bit late to
the discussions of writing one manual for more than one audience, and
whether too much information is a problem for readers. Here's what I did on
a manual for a software project some years ago.

The client wanted one manual for marketing, database administrators, and
data entry people. Although the last two groups were both "users" of the
software, the information needed by each of the three groups had very
little overlap. The client would not consider a series of books, each aimed
at a different audience, so I produced a book that had three clearly
defined parts, stated which part was for whom, and divided the information
to minimize overlap. The manager was happy with that solution, and (because
the whole thing was only around 100 pages) I agreed that it was a useful
document.

The programmer, however, was not at all happy with not having all sorts of
explanations and digressions in the data entry section. He argued that the
data entry people "needed to know" that information. I argued that I had
spoken to some of those people (who were almost exclusively temporary
typists brought in for a few days each month to do the data entry) and they
found the explanations etc confusing and in the way -- so they had given up
on using the old manual. (Does this story sound familiar?) I made their
section of the book into a very straightforward step-by-step set of
procedures, with diagrams showing where they were in the cycle of
end-of-month processes, and clear statements of what they needed before
they started, what to do, and what should happen if they followed the
procedure and the system worked correctly. I had short cross references to
a Troubleshooting section if whatever they were doing didn't work as
described. The Troubleshooting section contained most of the programmer's
digressions.

Other explanations and digressions, along with a lot of other technical
information which would only be needed (and probably only understood) by
the data administrator, went into another part of the book. Because
everything was in one book, data entry people could, if they wished, read
that information as well, but it didn't get in their way. And both data
entry people and the database administrator could read the marketing
section about features and benefits, and how this product fit in with other
products the company was using (it was a customized add-on to a more
general product; the main product had its own manual, which came with it).

So the manual I wrote contained all the details, but divided by audience.
The data entry people were delighted, and said so -- and questions to other
staff dropped dramatically, which delighted the manager. The programmer
remained irritated and unconvinced, but he left soon after anyway, having
done his job. I never found out what the data administrator (who joined the
company about the time I finished the book and left) thought of it.

One book in three parts would not have worked as well if the program had
required 1,000 pages of technical information, but in those circumstances I
think it would have been even more critical to extract the data entry
procedures and put them in a separate chapter, section, or book of their own.

Regards, Jean 
Jean Hollis Weber
mailto:jean -at- wrevenge -dot- com -dot- au
The Technical Editors' Eyrie  http://www.wrevenge.com.au/
Avalook at Australia Travel site: http://www.avalook.com.au/
-----------------
Now available: Electronic Editing, A quick start guide for editing
students, experienced editors making the switch from paper to online, and
anyone who needs to write or edit electronically. For details:
http://www.wrevenge.com.au/bookshop/e-edit.htm