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:Too-long books, take II From:"Geoff Hart (by way of \"Eric J. Ray\" <ejray -at- raycomm -dot- com>)" <ght -at- MTL -dot- FERIC -dot- CA> Date:Wed, 26 Aug 1998 12:43:16 -0600
Luigi Benetton provided more details on his long book:
<<This Reference Guide is for people who develop applications using a
proprietary computer "language". The bulk of its contents are two
sections that list all the Commands (300 pages) and Functions (400
pages) available to developers. Examples that help to clarify each
explanation typically take up lots of room, but developers say that
the examples are what make the guide useful.>>
Based on what you've said, I strongly suspect that there's an obvious
breakdown into two books (commands vs. functions). The sizes you
quote sound like they would be much more manageable for the user. I
also suspect that there are other obvious section breakdowns such as
"input/output", "data management", "graphics primitives", "control
structures", etc. that you could identify with a bit of work. For
example, you might be able to break things down into I/O (book one),
which would include all my examples except the control structures,
and some other category that would include the control structures and
other related information (book two).
<<We thought of splitting up the guide according to the type of code
document in which you'd use each command or function, but that would
cause quite a bit of duplication and result in eleven large
books...>>
Or perhaps two books, one with five chapters and one with six? Then
as the reference grew, maybe three books, with ca. 4 chapters each.
<<the developers in question travel to client sites to work on
implementation projects, and we don't expect them to haul along an
extra piece of luggage just for the documentation.>>
That suggests a solution. Create a book that lists the outlines of
each command, plus all the syntax, and put the examples on disk.
I'm assuming that the developers love to cut and paste, just like
the guys I'm familiar with, and mainly "look at" the examples so they
won't have to retype the algorithms from scratch. If you made
it easy for them to cut out the examples and paste them into their
programming software (the IDE), they'd quickly learn to appreciate
the slimmed-down paper books. Again, a testable hypothesis that you
can investigate through a usability study or audience analysis.
--Geoff Hart @8^{)}
geoff-h -at- mtl -dot- feric -dot- ca
"Men are from Earth. Women are from Earth. Deal with it."--Author unknown
