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.
I've got a monster of a reference manual for one of our software products
lying in front of me here, with a post-it saying "REWRITE!!". As much as I
like the assignment, I'm a bit at a loss where to start. 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, so if
you could help me out on that one, you have my eternal thanks (and remember
that eternal is veeeeeeeery long! *s*)
Here's some more information about the manual:
The manual has existed for several years, and during that time it has become
the product bible of over 500 pages long. All possible information about the
software is in there somewhere, but nobody knows where. Several writers have
added and edited information, but indexes and other entries into the
information are very limited.
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: there's
browsers for invoicing, browsers for clients, browsers for products etc.
The manual is intended for installation, configuration and reference
purposes only. The software is very complex and highly configurable, so
writing end-user instructions is not very useful. On the other hand, users
now complain that the information in the manual is too theoretical and not
usable in everyday situations.
About every three or four months, there's a new version release of the
software, so the information in the manual ages very rapidly.
My questions to you:
Has anybody out there experienced such a situation before? Any useful
advice?
I'm thinking of splitting this one manual into several smaller ones, e.g.
installation manual, configuration manual and reference manual. Are there
any pitfalls I should be aware of?
Has any of you tried a task based approach in reference manuals? I usually
prefer this approach to a software design approach, but in this case I don't
have enough of an overview to make a proper judgement on how long it will
take and what the advantages are.
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?
Thanks a lot!!
Maaike Groenewege
Tech Writer
Mediasystemen b.v., a Triple P company
Bloemendaal
The Netherlands
