Restructuring a monster manual--summary and thanks

[Maaike Groenewege <mgr -at- MEDIASYS -dot- NL>]

Thanks very much to the 31(!) people who took the time to advise me on how
to rewrite and restructure a 500 page monster reference manual. Here's a
summary of the points that appeared in almost all your replies (I've cut and
pasted snippets from the following people's replies: Andy, Geoffrey, Jeff,
Lisa, Maggie, Nancy, Rebecca, Robyn and Sonja--hope this is enough credit
*s*).

Preparation
Consult your users, consult your users and consult your users! Make sure
that what you think is best for them is also what they want.
Bear in mind that the company might be very attached to the manual as it is
now. Convince everybody concerned that you're not telling them the old
manual is crap, but that you're humbly offering your services to make it
even better (this point doesn't really apply in my situation, because
everybody here agrees that the old manual is not very good; the information
is there, but nobody knows where *s*).
Spend some time learning enough about the types of content in the manual
that you can understand how to group it more logically.
Make sure you consider media other than printed manuals. If the software
changes regularly, online help might be a more valuable investment than
printed material.
Use good planning and tracking, make a proper project out of this
assignment.

Structure
Break the document into smaller units (installation, configuration,
reference), but make sure that all relevant information about a topic is
present in one book. You don't want readers to have to use three books to
install a program. If you include the same content in different books, make
sure it's exactly the same, so that it's easily updatable. And again, make
sure that this is what your readers want.
Reorganise the chapters for an easier read; organise by task if possible.
Sometimes it is possible to mix task-based and conceptual information in one
manual; a good index will show the user where to find what.
Make one chapter devoted exclusively to screens; try to include as few
images as possible in the main text.

User friendliness
Include foldouts of frequent screens, buttons etc
Use simplified English; condense the writing
Create a multi-level index, conveying not only words, but also thoughts and
phrases.

I've presented these results to my manager, he sends a big thankyou too :o)
I'll be spending the next few weeks setting up a project plan and preparing
the analysis phase of the project. Anybody interested in how things are
progressing, please feel free to contact me off list, and I'll be happy to
send you a draft of the plan as soon as it is finished.

Maaike Groenewege
Tech Writer
Mediasystemen b.v., a Triple P company
Bloemendaal
The Netherlands

mgr -at- mediasys -dot- nl
http://www.mediasys.nl


 From ??? -at- ??? Sun Jan 00 00:00:00 0000=