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

Subject: Re: Brainstorming: Help vs Tutorial (why, concept, etc)
From: Kathleen MacDowell <kathleen -at- writefortheuser -dot- com>
To: dvora -at- tech-challenged -dot- com
Date: Thu, 23 Jul 2009 12:14:24 -0500

PDFs can add value beyond Help if you include bookmarks (and possible
internal TOCs). It's hard to have an in-depth TOC in Help, which I think can
be frustrating. By using bookmarks in a PDF, you can at least supplement the
TOC to present a more organized view of the topics.

A lot of what you'll want to provide depends on the complexity of the
product/topic, how similar it is to other programs people might have used
for the same purposes, and how mission critical the task is. If it's for
finances, defense, transportation, energy/nuclear power, or NASA (for
example), I'd hope they'd overdo their documentation.

Kathleen

On Thu, Jul 23, 2009 at 11:22 AM, Deborah Hemstreet <
dvora -at- tech-challenged -dot- com> wrote:

> Hi Robert, and Geoff,
>
> Thanks for your in-depth replies. The seem to support my thinking, but
> helped me picture better what I want to do and where I want to go.
>
> Robert, what is your take on how users handle the PDF? My client says
> they are not convinced the user will read a 30 page PDF with all of the
> conceptual information in it. They feel it will probably be more
> accessible in the help.
>
> I have mixed feelings. I believe we need both (and am planning on this).
>
> Well, back to work!
>
> Deborah
>
> P.S. and thank GOD I have work!
>
> Robert Lauriston wrote:
> > 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.
> > http://www.doctohelp.com/SuperPages/Webcasts/
> >
> > 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!
> http://www.helpandmanual.com/
> >
> > ---
> > You are currently subscribed to TECHWR-L as dvora -at- tech-challenged -dot- com -dot-
> >
> > To unsubscribe send a blank email to
> > techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
> > or visit
> http://lists.techwr-l.com/mailman/options/techwr-l/dvora%40tech-challenged.com
> >
> >
> > 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
> > http://www.techwr-l.com/ for more resources and info.
> >
> > Please move off-topic discussions to the Chat list, at:
> > http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat
> >
> >
> >
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> 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.
> http://www.doctohelp.com/SuperPages/Webcasts/
>
> 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!
> http://www.helpandmanual.com/
>
> ---
> You are currently subscribed to TECHWR-L as kathleen -at- writefortheuser -dot- com -dot-
>
> To unsubscribe send a blank email to
> techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
> or visit
> http://lists.techwr-l.com/mailman/options/techwr-l/kathleen%40writefortheuser.com
>
>
> 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
> http://www.techwr-l.com/ for more resources and info.
>
> Please move off-topic discussions to the Chat list, at:
> http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat
>
>
>


--
Kathleen MacDowell
www.writefortheuser.com
kathleen -at- writefortheuser -dot- com
kathleen -dot- eamd -at- gmail -dot- com
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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.
http://www.doctohelp.com/SuperPages/Webcasts/

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! http://www.helpandmanual.com/

---
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 http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


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
http://www.techwr-l.com/ for more resources and info.

Please move off-topic discussions to the Chat list, at:
http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat


Follow-Ups:

References:
Brainstorming: Help vs Tutorial (why, concept, etc): From: Deborah Hemstreet
Re: Brainstorming: Help vs Tutorial (why, concept, etc): From: Robert Lauriston
Re: Brainstorming: Help vs Tutorial (why, concept, etc): From: Deborah Hemstreet

Previous by Author: Re: Red SAVE Button - Thank you Thank you
Next by Author: Re: Red Button - O MY! (end of that story - for now) - and NEW question
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