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.
Interesting that you mention such a "monster" task. This has been my
specialty for some years.
First of all, as you stated, break the document into smaller units; possibly
different books. Reorganize the chapters for an easier read. In the process,
the look-and-feel (formatting) of the document should be changed to a more
spacious, less confusing one. By "modularizing" the document(s) you can
alleviate some of the problems associated with the fast-changing software.
Hopefully, only small document sections will be affected by the changes.
Second, if you have a lot of graphics of software screens, consider making a
chapter devoted exclusively to the various screens. I used this method on
the Ground Based Software Tool (GBST) for the Boeing 777, which was
5,000-some pages. Each screen was listed alphabetically, a screen-captured
graphic of each screen was shown and described. Each pull-down menu and
button was described including a graphic(s) of the choices available from
each menu and button. This "screen" section covers everything that a user
would want to know about every screen that they may encounter. If you have
several different software products, such as the GBST, which was actually 6
different tools, you should separate each product into its own book/document.
If the software is complex, which it sounds like it is, consider including a
section (for each product) that contains 11 x 17 graphic foldouts showing
the paths available from each menu and button for each different software
product. Boeing loved this!!
Use SIMPLIFIED ENGLISH. Keep the sentences short, approximately 15-20 words.
Don't get "wordy". Be concise. In this case, you are not paid by the word.
Also, be consistent in technical term usage.
Third, separate all installation info into a separate document. The GBST had
1 installation document with a section for each of the 6 tools.
Fourth, create a multi-level index. This can be a task in itself. I'd
suggest spending at least a week developing the index for each section. It
should not be taken lightly, it takes a really good tech writer to "think
like a user" when creating an index. A multi-level index (using index
markers) lets you convey thoughts and phrases; often using words not
included in the actual document.
Keep in mind, from the start of a project to the end of a project, on
average a good technical writer usually produces 4 to 4 1/2 pages per day.
Maaike, what software are you using? Interleaf Publisher, though expensive,
is perfect for this type of task.
Nancy Kendall
Sr Documentation Analyst and Owner
Kendall Custom Documentation
