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:types of information and structure question From:Becca Price <becca_price -at- yahoo -dot- com> To:"TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com> Date:Fri, 19 Jan 2001 10:16:21 -0800 (PST)
Question: What general types or categories of information should
be covered in a software manual? I have interface information,
procedures, reference, and conceptual information to guide the
user in making intelligent choices when selecting options or
designing formulas. Am I missing anything?
Background: I'm currently analyzing our documentation, with an
eye toward reorganizing it (which it desparately needs). I'm
responsible for the administrator's guide to a very
sophistocated, large, and complex financial database system.
The Admin Guide covers everything from setting up the database
and installing it to how to intelligently design formulas to get
the correct results from the data.
In one manual (which is getting large and unwieldy), we have
interface information (field definitions and procedures on how
to use the various components of our products), reference
information (what parameters you can set and when and why you'd
use them), and what I can only think of as theoretical or
conceptual information (the afforsaid information on how to
design the formulas).
What's not covered, but is really necessary are process
procedures: adding a new user, for example, which can require
one to use several components plus editing and running various
SQL scripts.
The admin guide is developed in Word, and delivered as a PDF. In
addition to the Admin Guide, we have online help. This is
mostly procedural, with some reference material and examples.
The intent for the Help is to provide procedures and examples
that a user can copy from the Help file and paste into the
appropriate field and then modify to fit their situation.
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.
Has anyone else faced this issue? how have you solved it? (and
no, I can't look at competitor's documentation, unfortunately -
their approach to providing the same functionality is *entirely*
differnt from ours).
There's no such thing as useless information, only information for which you haven't found a use yet.
__________________________________________________
Do You Yahoo!?
Get email at your own domain with Yahoo! Mail. http://personal.mail.yahoo.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) 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.
