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: On-line help and manuals From:Marguerite Krupp <mkrupp -at- WORLD -dot- STD -dot- COM> Date:Fri, 10 Feb 1995 08:35:57 +0001
The point of the software is (or ought to be) to provide a consistent,
accessible, useful document for the user, regardless of the presentation
medium.
Companies like to think that the point of the software is to save time
(and therefore money), and that effect may occur, but that's not what the
business of technical communication is about.
My experience has been that when people try to make a 1-for-1 transfer
between hard-copy and online documentation, one works well,, and the
other's abysmal. The point is that people use these two types of
documents differently. (This is based on experience with online
documentation competitions going back to 1984.)
While there ain't no free lunch, there are some definite wins. If you are
aware from the start that you will be using the same text, you can set
some standards for yourself. Think about transitions in both media. Think
about references and jumps. Think about synonyms, since users may not
think about the product in the same terms you're used to. How would users
of a similar product, building on their previous knowledge, relate to
your product - what terms would they use?
I like Doc-To-Help for a lot of reasons. Just realize, that it's not the
complete answer. If you want to use the same text (or most of it), you
can do so; and the users will see a fine consistency between them. That's
good. But as you seem to recognize in your posting, using this tool well
(and for the benefit of the users) still requires a lot of work and
forethought.
Marguerite
On Fri, 10 Feb 1995, Suzanne Townsend wrote:
> I'm interested in the responses to this one. I'm beginning a new manual
> and on-line help, using Doc-To-Help, and ASSUMED that the on-line help
> would be taken from the manual -- i.e., a one-write system. It means
> writing the manual slightly differently, and of course leaving out
> portions of the printed manual, but isn't the point of this software to save
> time?
> > Techwhirlers,
> >
> > We are developing our first Windows<insert trademark symbol> product,
> > and I am fortunate enough to be developing the on-line help. I am using
> > Doc-To-Help
> > as our help tool.
> >
> > In a perfect world, the on-line help document and the manual document would
be
> > separate beasts. However, due to time, staff size (2), and all of the other
> > regular inhibitors, we are trying to determine whether or not these
documents
> > can be (or should be) one in the same. Whatcha think?
> >
> > FYI, Doc-To-Help has a neat little feature that allows you to designate
> portions
> > of the document as Manual or Help only. This sounds like it could resolve
some
> > issues.
> >
> > Thanks in advance,
> > --
> > Dan Glovier
> > dan -at- tsh -dot- com
> >
> > "Wanna go back to fifth grade, but I'd be 23."
> > - "What It Is" Too Much Joy
> >
