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.
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 archive -at- web -dot- techwr-l -dot- com -dot-
