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:Do we need separate training guides? From:Geoff Hart <ghart -at- videotron -dot- ca> To:techwr-l List <techwr-l -at- lists -dot- techwr-l -dot- com> Date:Mon, 24 Sep 2007 10:53:41 -0400
Daniel Ng wondered: <<We are currently have online help for our
software built with robohelp. Our project deployment engineers,
arelooking forward to a printable training guide. Do we need to
develop two different sets of documentation, one a training guide and
another branch of documentation for online help.>>
Yes, you do. A training guide trains; documentation documents. That's
a bit glib, but it highlights the difference: When you are training
people, you decide first on the key learning objectives, and create
lessons designed to support each objective. By the time readers have
read the entire manual, they are trained: they can accomplish what
you have identified as the key tasks, and (hopefully) have also
learned to use the documentation. No, really: I proposed to the
trainer at a former workplace that he teach everyone to use the
online help, and students apparently loved this, and his support
calls dropped considerably. Wish I'd thought to document the details!
In contrast, documentation is what you use to solve problems for
someone who already knows how to basically use the product. In one of
Karen Schriver's studies, 81% of the users of a product only
consulted the documentation to find answers to a specific question.
That number should not be abused to support our biases about all
products and all audiences, but it does illustrate the important
point: the majority of people use documentation exclusively to answer
a question, not to learn the software.
You can, of course, include a training component in documentation. I
have vague memories of an early RoboHelp manual choosing this
approach (each chapter was a lesson about how to use certain
components of the software), and I found it very effective as a
learning tool: by the time you'd finished reading the book, you
basically knew how to do all the important things you wanted to do
with the software. But it was less effective as a reference tool. For
reference, I typically turned to the online help because of the
search function and index.
One really interesting approach I've used successfully in the past
was to combine the two approaches in a single help file. For example,
I provided a start screen that presented two pathways into the Help
file: Pathway 1 was a tutorial composed of a series of lessons that
led users through typical tasks. Pathway 2 was the menu- and dialogue-
level help. In the tutorial, I provided hyperlinks to each of the
relevant reference sections ("click here if you need more information
about the X command"), opened as a secondary window that clearly
revealed that the tutorial sequence was still there in the
background. That way, nobody ever lost their place in the tutorial;
to avoid spawning dozens of windows, I was fairly stingy about doing
this from anywhere other than the tutorial. Conversely, in the
reference, I provided links to tutorials that showed how the command
or menu or dialogue fit within the larger scheme.
<<* The training guides (MSWord) are grouped into different job areas
or positions, since different users use different features of the
products, derives information from the help files, with review
questions at the end.>>
That's a reasonable split, but it's always worth analyzing whether
this is the right approach. Sometimes there's enough overlap between
groups in the tasks they perform that it's more important to group
the guides into collections of related tasks, which may not precisely
match the job descriptions. People who don't need to accomplish a
particularly goal won't bother reading about tasks that don't concern
them, and you can produce exactly the same help file for all
audiences, provided you do one thing: provide a different table of
contents (TOCs) for each audience. The content of the help file is
identical, but how people access it (i.e., via the TOC) differs. And
if you guessed wrong about what someone needs to see, you haven't
prevented them from finding that information: it's still there in the
overall help file.
In your case, one of your problems is that you're worried about reuse
of content (i.e., too much copy and paste, then having to remember to
revise a reused chunk everywhere it is reused). The approach I've
suggested above may provide a simple solution. Not everyone likes it,
however; among other problems, it does not rigorously exclude users
from seeing topics "that they're not supposed to see". I don't
generally consider that a serious problem, but in some cases, it is
serious.
You can also look into single-sourcing. This may be as complicated as
a dedicated single-sourcing software solution, or as simple as
creating the reusable text as separate documents, and using Word's
"includetext" field to import that text from an external document.
(Then, you have to remember to update fields every time you open a
document for editing to ensure that the document will contain the
most recent version of the reusable text.)
I suspect that as the amount of reuse grows beyond a few dozen
external files, Word's approach will become increasingly cumbersome
and unmanageable. But for simple situations, it may accomplish
exactly what you need if you've analyzed the modularity of your
topics sufficiently well.
----------------------------------------------------
-- Geoff Hart
ghart -at- videotron -dot- ca / geoffhart -at- mac -dot- com
www.geoff-hart.com
--------------------------------------------------
***Now available*** _Effective onscreen editing_
(http://www.geoff-hart.com/home/onscreen-book.htm)
Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include support for Windows Vista & 2007
Microsoft Office, team authoring, plus more. http://www.DocToHelp.com/TechwrlList
True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
