RE: types of information and structure question

Subject: RE: types of information and structure question
From: "Michele Marques" <marquesm -at- autros -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 19 Jan 2001 13:43:15 -0500

Becca Price asks a number of questions about structuring manuals, including:
> My boss *really* doesn't want to split the Admin Guide into a
> User's Guide and a Reference Guide. But each type of document
> requires a different approach: a user guide should have
> task-based procedures; the reference guide really should be
> structured by the individual components within our overall
> product.

I handle this by having a user's guide, and making sure that all software
elements (screens, menus, buttons, etc.) are described somewhere in the
task-based user's guide. I index all menus, menu options, screen names, etc.
so that someone trying to look up that information as a reference (i.e.,
looking alphabetically) can find it in the index, and then know where to
turn in the user's manual.

Generally, I split out components of an application into separate manuals:
- by user group, e.g., if there are different audiences who use different
parts of the program (or use it in different ways)
- by when the components are used (e.g., create a separate "getting
started" guide)
- by functional area or component, if the application is to large to be

documented in one manual (e.g., when there are 5000 pages of documentation).

On the other hand, sometimes separate user and reference manuals work. I
remember that, at least at one time, SAS (big statistical package) had a
one-volume user manual and a multi-volume reference manual. The one-volume
user manual took users through basic functionality with common statically
procedures and new-user issues, while the reference manuals documented
everything about every procedure and command you could issue. I found this
really useful when I was supporting SAS users.

Michele Marques
Technical Writer,
Autros Healthcare Solutions
marquesm -at- autros -dot- com

Develop HTML-Based Help with Macromedia Dreamweaver 4 ($100 STC Discount)
**WEST COAST LOCATIONS** San Jose (Mar 1-2), San Francisco (Apr 16-17) or 800-646-9989.

Sponsored by DigiPub Solutions Corp, producers of PDF 2001
Conference East, June 4-5, Baltimore/Washington D.C. area. or toll-free 877/278-2131.

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 for more resources and info.

Previous by Author: RE: Multiple pdfs from FrameMaker
Next by Author: RE: Requoting other companies' docs in your own docs
Previous by Thread: types of information and structure question
Next by Thread: video screen capture with dynamic text

What this post helpful? Share it with friends and colleagues:

Sponsored Ads