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: Online Documentation vs. Help From:"Wing, Michael J" <mjwing -at- INGR -dot- COM> Date:Wed, 10 Dec 1997 17:54:01 -0600
> Just a theory--feel free to take pot shots at this one:
>
<snip>
> Might the appreciation level of the audience really be an issue of
> "know
> your audience" and also HOW technical the material is? Consider the
> following "formula":
>
> higher technology (of material) = higher knowledge level of users
> THEREFORE less need for procedural help AND higher need for reference
> help
>
> Larry Weber
> larry_weber -at- hotmail -dot- com
>
OK, I'll shoot. Higher technology of material does not necessarily
equate to less need for procedural help. For example, a mechanical
designer may be an expert in the mechanical field. However, they may
not be an expert in CAD software. If you are documenting the mechanical
design software, you are not teaching them how to design a machine - you
are teaching them how to use your software to perform functions they
normally did by hand. Therefore, the procedural steps may be necessary
to make them familiar with the approach that the software uses.
For example, the Mechanical designer at one time used a protractor
and/or compass to draw a curved piece of the machine. They may also
have used a stencil to do the lettering. With the CAD software, they
may have to invoke a GUI that allows them to define a BSpline curve.
This would include tolerances, length, angle, and so forth. It would
also include rendering (line width, scale, . . .). The software may
then require them to draw the wireframe for the mechanical piece. The
lettering, would be another function. The designer knows what is needed
but may not know that the lettering, part parameters, and actual
drawing/editing of the part are different software procedures (let alone
where to invoke the applicable commands and in which order to perform
them).
IMO, reference and procedural online help perform different functions.
The online reference help describes each of the software parts but is,
for the most part, oblivious to the interrelationships between the
parts. Users typically go to a reference topic to get a specifics. For
example, they may be in the lettering function, but can't remember what
font choices are available.
The procedural online help is a more holistic approach to the material.
The procedural help allows the user to become familiar with doing
through the software what they use to do by hand. It says 'this
function must be done before this function can be started'. The
procedural material can be more generic. It's more workflow oriented.
Because it's online, links can exist between the relevant reference and
procedural topics to allow the user to display details as they read the
workflow or to get procedural information as they look at specifics.
The user relies on the procedural material more as they are learning the
software or relearning a process they haven't done in a while. As they
become familiar and comfortable with the procedural online help, they
will probably use the reference help more often.
