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.
Maaike Groenewege has <<...a monster of a reference
manual for one of our software products lying in front of me
here, with a post-it saying "REWRITE!!".>> Fun!
<<I've already had some meetings with users (company
employees who use the manual for installation purposes, as
well as system administrators who use it for product
maintenance). Although they have given me useful advice on
the contents, I'm still a bit puzzled about what to do with the
structure...>>
Well, my first thought is that if they've been willing to help
this far, why not go back to them and ask for opinions on
structure too? It's a good bet they'll provide better information
than we can, since they're (I assume!) your actual audience.
That being said:
<<All possible information about the software is in there
somewhere, but nobody knows where.>>
That suggests two things: first, spend some time learning
enough about the types of content in the manual that you can
understand how to group it more logically; second, invest
some time in generating an effective index. Indexes are
expensive and time-consuming, but for a large printed
manual, they're probably one of your best investments: if
nobody can find the information, it doesn't matter how well
it's written.
<<The manual contains lots of similar screens; for instance,
there's a whole lot of browsers, a whole lot of entering
screens, etc. But these screens are spread across several
different tasks/topics in the software...>>
Piece of cake (at least potentially) if you think laterally
(literally!): insert the frequently repeated screenshots, one per
page, at the back of the book, but produce them as double-
size pages that fold out beyond the margins of the main
printed pages. That way, the users can look at the text on the
two-page spread, and glance to the right at the diagram when
they need to orient themselves. This works best for smaller
manuals (since it greatly increases the desk space required to
lay the manual flat), but it can work marvelously well in some
situations. It also increases printing cost, but not horribly, and
the cost might be particularly easy to justify if you adopt
some of my suggestions later in this message.
<<The manual is intended for installation, configuration and
reference purposes only.>>
This suggests three distinct books, provided the information
doesn't overlap (i.e., so that nobody ever has to face the
nightmare of spreading out three open manuals on their knees
and trying to use all three while staring at the screen). But
confirm that producing separate manuals would be really
useful by asking your audience.
<<The software is very complex and highly configurable, so
writing end-user instructions is not very useful.>>
This suggests that online help is going to be much more
effective than the printed manual, at least for much of the
information. In effect, when users want to configure
something, they click the help button and up pops the specific
configuration (or reference) information for that screen. This
would be far more helpful than trying to find the same
information in a printed manual. Moreover, the configuration
information is more likely to change (and need to be updated)
than the overall concept of how to work with the software;
putting it online eases the task of updating the user-support
information with each release.
<<On the other hand, users now complain that the
information in the manual is too theoretical and not
usable in everyday situations.>>
Which suggests that the three manuals I proposed earlier need
to include both task-based and reference-based sections,
possibly in separate sections or books. Sometimes the
different information can share the same pages (e.g., the task
information comes first, under its own heading, and the
reference information comes last, under a second heading).
Sometimes it's better to put the reference information online
and leave the task information in print. Ask your audience!
<<About every three or four months, there's a new version
release of the software, so the information in the manual ages
very rapidly.>>
See my previous notes. This _strongly_ suggests that most of
the reference and configuration information belongs in online
help. The task information probably doesn't change much, so
it can stay in print. If you go with the online help solution,
make sure you start building bridges with the developers so
that they keep you up to date on changes (so you can update
the help files).
<<Has any of you got tips on how to make a highly technical
document less difficult to read while keeping all the relevant
data in there?>>
Dozens of tips... I could write a book! <g> Best bet would be
to provide us with specific examples as you start doing the
work, and let us provide specific advice rather than unhelpful
generalisations (e.g, "avoid passive voice").
