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:Re: Organization of User's Guide From:K R Wolfe <keith -at- MERGE -dot- COM> Date:Thu, 7 May 1998 10:09:36 -0500
I write user and service manuals for our products. Our user manuals seldom
require any conceptual stuff, but our service manuals always do. I suggest
a chapter dealing with the conceptual stuff titled 'Theory of operation,'
or something like that. Your users who know that information can just skip
over the chapter, while others won't.
Two things can happen if you place relevant conceptual info in the
beginning of EACH chapter.
(1) Users who don't need the info have to determine where they need to
start reading in every chapter. Think about how this will slow them down.
(2) Users who do need the info get a fractured view of the whole.
Some questions to ask yourself:
* Is the material worthy of it's own chapter?
* Will your readers benefit more from a macro view, or two or three micro
views of a whole?
* Is the nature of the information such that a fractured micro view could
be benefitial?
* What do your users expect from previous documents? Developing a schema
is very important. Violating a schema can be bad. Make sure it's worth it
before you revamp a format.
