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: 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.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Develop HTML-Based Help with Macromedia Dreamweaver 4 ($100 STC Discount)
**WEST COAST LOCATIONS** San Jose (Mar 1-2), San Francisco (Apr 16-17) http://www.weisner.com/training/dreamweaver_help.htm or 800-646-9989.
Sponsored by DigiPub Solutions Corp, producers of PDF 2001
Conference East, June 4-5, Baltimore/Washington D.C. area. http://www.pdfconference.com 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 http://www.raycomm.com/techwhirl/ for more resources and info.
