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.
Online help and manuals are documents that exist in different media, with
different goals.
Different media: Explaining a concept in 120 lines (or 80 lines and a
graphic or two) that span two facing pages is fine in a manual, but makes
a very cumbersome help topic. A help topic that contains ten or twenty
references to popups is fine - a page that contains ten references
(unless
it's an index or something) is a horror to read.
I predict that online help will continue to become more interactive and
automated, and less like a printed manual as the technology evolves.
(Gee - this Huber guy makes risky predictions-NOT.)
Different goals: When a reader opens a manual, the reader wants to learn
about something. When a software user presses F1, the software user wants
a question answered.
Which approach (minimal manual/maximum help VS
maximum manual/minimal help) depends on the product being documented.
Some software involves complex concepts that can only be addressed well
in a manual, and a fairly simple user interface that requires a lean help
file with references to a couple of big topics. (I'm working on such a
project
now. It's a statistical process control package. Big concepts - little
UI.)
Other software is much less conceptual, but needs more help. I'm thinking
of the graphics package I worked on recently. The approach I advocate is
printed documentation that educates the reader and online help that
answers
the immediate question first, with pointers to the whole story.
This does not seem to me to be one of those issues where standardization
leads to synergy for the customer. While we might be able to use
standardization to come up with a single development model instead of
adapting the process to the task at hand, our convenience must remain
subordinate to the customers needs.
----------
From: Starr, Mike[SMTP:Mike -dot- Starr -at- software -dot- rockwell -dot- com]
Sent: Tuesday, September 26, 1995 10:09 AM
To: Multiple recipients of list TEC
Subject: Printed vs. Online: What mix?
I'd like to get a feel for how other companies out there blend printed
and online software documentation. My own personal inclination is to
develop a complete and thorough manual, then convert that same
information into a complete and thorough help file. Some people feel that
there should be a minimalist manual and a complete and thorough help file
(the Microsoft approach); others feel that there should be a complete and
thorough manual and a minimalist help file. I think that whatever
approach is taken it should be the same approach for all of a company's
products, thus the decision should probably be a prerogative of upper
management. How do you vote?
1. Comprehensive printed/comprehensive online
2. Minimal printed/comprehensive online
3. Comprehensive printed/minimal online
Mike
Mike Starr
Writer
Rockwell Software Inc.
mike -dot- starr -at- software -dot- rockwell -dot- com
