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 had a similar situation. I was handed two functional specs that were more
than 300 pages EACH. (They are FrameMaker docs.) Chapter 4 was 1/3 of the
doc and was split into two files! They, too, had been written by several
writers, code was a mess, and it was loaded with graphics. The functional
analysts thought my sole purpose was to rewrite what they told me to, not
edit what needed to be done.
I took a chance and put the doc in a new, clean template.I converted the
graphics to GIFs and did some format changes. Boy were they mad. They did
not care that the document was unmanageable or that autonumbering was very
difficult. The only thing they approved was the GIFs. Ultimately, I had to
put the doc back into the original template, regardless of the code problems
or anything else.
Here's what I learned: The project, team or company is incredibly attached
to documents such as the ones you and I worked on. I learned that the only
way the team will let you make the necessary changes is to get a mandate
from the "big boss" or someone very close to his level. I learned other
things to, but they included leaving the project :>)
Sonja Waller
Sr. Technical Writer
Smallworld Systems, Inc.
Communications Business Unit
TEL: 303.268-6163
FAX: 303.779-9945
Email:
sonja -dot- waller -at- smallworld-us -dot- com
-----Original Message-----
From: Maaike Groenewege [mailto:mgr -at- MEDIASYS -dot- NL]
Sent: Tuesday, April 13, 1999 8:29 AM
To: TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU
Subject: Restructuring a monster reference manual
Hello all!
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
