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

Subject: Re: Brainstorming: Help vs Tutorial (why, concept, etc)
From: Robert Lauriston <robert -at- lauriston -dot- com>
To: TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Thu, 23 Jul 2009 09:12:39 -0700

In one doc I'm particularly happy with, I have an introductory
reference topic that outlines the typical workflow. There are 30 steps
in the workflow, and each has cross-reference hyperlinks to detailed
how-to topics for specific tasks. For example, the first step is
"Create a new project file," which has a link to an overview topic
"Creating Project Files." This topic includes whatever general
information the user might need to know about creating project files,
followed by links to how-to topics for all the various ways the user
do that (create a blank project, create a project from a template,
retrieve a project from the server).

When helpful, how-to topics start with prerequisites, as Geoff
describes. They may contain links to the workflow outline or other
how-to topics to help the user figure out what to do next. The how-to
topics are grouped and sequenced along the same lines as the workflow.

Within the workflow, there are many conditional branches and iterative
loops. For example, step 17 is a unit test for one element of a task,
and a project may contain many tasks. If the output from the test is
wrong, the next step is to debug; if the output is correct, the next
step is to add another element to the task (go back to step 11), or,
if all elements have been added, to test the complete task with live
data (go on to step 18).

How-to vs. tutorial: A how-to topic covers a relatively simple
low-level user task, such as creating, saving, or deleting a file
("using a dialog box" is NOT a task), and is intended to assist people
using the product to do real work. A tutorial covers a relatively
complex high-level task with many steps, typically from the creation
of a file or opening a sample file through to final output or
completion, and is intended for new users and people evaluating the
product (so tutorials have more of a marketing function than how-to
topics). Tutorials should reflect best practices and be supplemented
by one or more sample files.

I always deliver the online help as a PDF user guide as well.

On Thu, Jul 23, 2009 at 6:07 AM, Deborah
Hemstreet<dvora -at- tech-challenged -dot- com> wrote:
> Hi All,
> I'm trying to think out of the box, and but my box has chains...
> 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.) ...

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: Re: job-hunt weirdness
Next by Author: Re: job-hunt weirdness
Previous by Thread: 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