Brainstorming: Help vs Tutorial (why, concept, etc)?

Subject: Brainstorming: Help vs Tutorial (why, concept, etc)?
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: TECHWR-L Writing <techwr-l -at- lists -dot- techwr-l -dot- com>, dvora -at- tech-challenged -dot- com
Date: Thu, 23 Jul 2009 10:21:44 -0400

Deborah Hemstreet wondered: <<When working on online Help, how would
YOU distinguish between the pure HOW TO (delete, add, use a dialog
box, etc.) vs Why would I ever want to do this to begin with.
Conceptual information that, without knowing this up front, you'll
never know you NEED to add, delete, etc.)>>

Start by understanding what readers need to know before they actually
begin reading the details. Think of these as "critical points of
failure": if they don't know this critical information, they will
fail. For example:
"Before you can do this procedure, you must have done the following
procedures or have the following materials available [list]"
"Before proceeding, make sure you have identified all the directories
you must include in this procedure and ensure that you have the
permissions you require to work on these directories."
"Ask all other people to leave the room before you begin this
"Before continuing, confirm that your breathing equipment is working
correctly and confirm that you have at least 1 hour worth of oxygen (X
psi) in the tank."

That's the essential context you should provide. There may be
additional context that's useful, such as shortcuts, cross-references
to related topics, and so on. The question to ask is what the reader
needs to know. In procedural information, people already know why
they're using a product feature, but may not know how that feature
fits into the overall process of achieving a larger goal. In reference
information, they don't know what something does, let alone why they
might use it, so you need to provide even more context: what does this
feature actually do, and how does that fit in with my overall goal of
getting home by 6 PM?"

<<Do Tutorials provide the concept as well as the how to?>>

Yes. Tutorials must provide an overview of what you're going to learn
and how it fits into the overall picture. This is how people assemble
isolated bits of knowledge (e.g., a tutorial on a single procedure or
tool) into the ability to use a product (i.e., by combining a series
of procedures to accomplish a larger goal). The goal of a tutorial is
to show people how to accomplish some task (en route towards
completing a goal composed of two or more tasks); the goal of online
help is to provide the details once you already know the overall flow
of the work.

Where many tutorials fail is that they do an excellent job of
describing a procedure, but don't relate it to any other procedures --
thereby forcing the reader to look at the complete list of tutorials
and try to figure out how they fit together and in what sequence.
Often, that's not at all obvious.

Geoff Hart (
ghart -at- videotron -dot- ca / geoffhart -at- mac -dot- com
Effective Onscreen Editing:


Free Software Documentation Project Web Cast: Covers developing Table of
Contents, Context IDs, and Index, as well as Doc-To-Help
2009 tips, tricks, and best practices.

Help & Manual 5: The complete help authoring tool for individual
authors and teams. Professional power, intuitive interface. Write
once, publish to 8 formats. Multi-user authoring and version control!

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Please move off-topic discussions to the Chat list, at:

Brainstorming: Help vs Tutorial (why, concept, etc): From: Deborah Hemstreet

Previous by Author: Red SAVE Button?
Next by Author: RE: Importing DITA into RoboHelp
Previous by Thread: Re: Brainstorming: Help vs Tutorial (why, concept, etc)
Next by Thread: Re: Brainstorming: Help vs Tutorial (why, concept, etc)

What this post helpful? Share it with friends and colleagues:

Sponsored Ads