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: TOC for an Administrator Guide From:Todd Snarr <todd_snarr -at- AUTOSOFT -dot- COM> Date:Tue, 23 Dec 1997 07:57:16 -0700
David asked:
>I am about to write a Administrator's Guide. What is the best structure and
>content for such a book?
The best structure for such a book? I guess it depends on the actual tasks of the administrators that are using your product. What do they need to do to get their job done? What is their job? Do a task analysis and then chunk those tasks into logical chapters. (That is, if SEQUENCE is important. If not, you could structure it as a reference guide, alphabetically by topic...and then have key tasks under those topics.)
I just wrote such a guide for administrators in the warehouse management industry (for a warehouse managment system). Configuration and management were key tasks. The TOC looked something like this...
About This Guide
*Purpose
*Organization
*Conventions
*Related <product> Information Products
1: Getting Started
Key Terms
*Preparing Your Site
*Installing <product> (could go into an appendix, since this is a one-time task)
*Loading <product> on RF Terminals
*Starting and Shutting Down
2: Configuring Your System
Key Terms
*Setting Up Users
*Setting Up Warehouses
*Setting Up Zones
*Setting Up Locations
*Setting Up Hardware Devices
*Setting Up Host Communications
*Setting Up Customers
*Setting Up Vendors
*Setting Up Items
3: Managing Your System
Key Terms
Backing Up the <product> Database
Backing Up <product> Application Programs
Restoring the <product> Database from Tape
Displaying <product> Deep Processes
Shutting Down <product> Deep Processes
Starting <product> Deep Processes
Rebuilding Index Files
Working with Transaction Files
4: Troubleshooting
(Probably the most important chapter, and hardest to write)
Appendixes
The tasks here are far from complete...but this might give you an idea. I think the key is to identify as many tasks as possible, and then chunck them into main tasks, subtasks, etc.
Todd Snarr
Senior Technical Writer
Auto-Soft Corporation
Salt Lake City, UT
