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.
Subject:Manual Design 101? From:geoff-h -at- MTL -dot- FERIC -dot- CA Date:Wed, 26 Feb 1997 13:35:59 -0600
Anne Chenette asked for quick info on how to produce a new
design for a set of manuals. Hmmm... can I get back to you
on Wednesday after I've finished cleaning out the Augean
stables? <Fe>
Sarcasm aside, it would take a reasonably long textbook to
give you everything that you need to know; instead, I'll
content myself with something more practical based on a "do
it yourself" approach so you can get up and running
quickly:
1. Make a list of all the components that your
documentation must include; do this both at a high level
(e.g., tutorials, screenshots, reference info., indexes,
etc.) and a low level (headings, paragraphs, captions).
2. Round up all the software manuals available in your
office (there should be dozens), and have a look at each
one in the context of the list you created in step 1.
3. For each component you listed in step 1, identify which
approaches worked for you (as reader and user of the
manual), and which ones didn't. Try to understand why. Pick
the best aspects of each approach and make them part of
your own approach.
4. Repeat steps 1-3 periodically over the next few years,
just before you release your revised docs. Combine this
with occasional surveys of your audience to see what they
do and don't like. In fact, the audience analysis should be
step pre-1, but it doesn't sound like you've got time for
that in your current situation.
--Geoff Hart @8^{)} geoff-h -at- mtl -dot- feric -dot- ca
Disclaimer: Speaking for myself, not FERIC.
TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot- Send commands
to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
Search the archives at http://www.documentation.com/ or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html
