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.
Dawson McKnight wonders <<One Doc or Multiple Docs?>>
Actually, I prefer a good paradox any day. <g>
<<Do you provide installation, administration, configuration, and
troubleshooting guidance in a single document (e.g., an "Administrator's
Guide"), or do you provide each of these kinds of instructions in a
different document?>>
The way I look at it, if different people will be using the information, you
need different books (in the extreme case, one per person). Think of it this
way: if you keep everything in the same book, then two of these three people
will have to make the trek to the third person's office every time they need
to look something up. Another factor that could affect the choice might be
size: a 6-inch thick book that combines all three would be unusable, whereas
three 2-inch books might work far better. Then there's the issue of whether
the book will be available online too; if so, then having only a single
physical book might not matter.
<<Without a substantial user base, how can I determine how consolidated my
documentation set should be?>>
Talk to anyone in your company who understands the target audience (e.g.,
sales staff, telephone support staff, trainers) to get a picture of how
people work with your products. This will give you some indirect insight
into how they're likely to use the documentation for those products too.
<<As I look at the existing documentation set (five documents total, 50-70
pages each), I feel that it should be consolidated into a single document,
perhaps an "Administrator's Guide".>>
Sounds like a reasonable approach, particularly if the jobs will all be done
by one person (the administrator). 350 pages isn't unmanageable for a single
manual. Given your description of these five manuals (Installation guide,
Overview, Administration guide, Configuration guide, and Troubleshooting
guide), it sounds like they belong together anyway.
<<We are distributing the documents electronically, so physical access to a
book isn't a problem, either.>>
That pretty much confirms that a single book is likely to work just fine.
"Technical writing... requires understanding the audience, understanding
what activities the user wants to accomplish, and translating the often
idiosyncratic and unplanned design into something that appears to make
sense."--Donald Norman, The Invisible Computer
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Learn how to develop HTML-based Help with Macromedia Dreamweaver!
Dec. 7-8, 2000, Orlando, FL -- $100 discount for STC members. http://www.weisner.com/training/dreamweaver_help.htm or 800-646-9989.
Sponsored by SOLUTIONS, Conferences and Seminars for Communicators
Publications Management Clinic, TECH*COMM 2001 Conference, and more http://www.SolutionsEvents.com or 800-448-4230
---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.
