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:Organization of User's Guide From:Donna Marino <dmarino -at- DECISIONISM -dot- COM> Date:Wed, 6 May 1998 16:43:20 -0600
I am writing a user's guide for a database management application and would
like some advice about how to structure the document. There are three types
of information that must be included in the guide: procedural, conceptual,
and strategic information. There is a lot of conceptual info (high level
overview of how the application works, with illustrations), and equal
amounts of both strategic and procedural information. The procedural
information basically tells the user what information to enter and which
buttons to click. The strategic information discusses how to maximize the
application for the type of database being used. I am combining the
procedural and strategic information.
My question is where to put the conceptual information. Do I put the
relevant conceptual info at the beginning of each chapter? I don't want to
burden the reader with this if he/she is not interested in reading it or if
the user already knows the concepts. However, the conceptual information
will give the novice user a better understanding of how to use the
application. The other possibility is to put all the conceptual information
into one chapter and refer the user to that chapter. If they want to read
it, they will know where to find it. Questions/comments? Please send them
to me offline; I will summarize the postings I receive.
Please note, I am interested only in advice about where to put the
conceptual info. The rest of the document's organization has already been