Documenting complex tasks in Online Help

Subject: Documenting complex tasks in Online Help
From: "Andrew T. Brooke" <abrooke -at- pathcom -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Mon, 9 Sep 2002 09:57:08 -0700

This is my first post to TECHWR-L, so I apologize in advanced if this
question has already been discussed.

My question is: in a online Help project, what do you find is the best
approach to document very complex tasks, tasks in which one or more previous
tasks must be completed before the final task can be done?

I had a project recently for a web-based application in which the user would
often have to go through 3-5 operations or screens before they arrived at
the screen that allowed them to do a particular function, or "final task".

I basically felt I had two options in documenting the final task:

1. Prefacing the task with the following hyperlink:
First, do this task: <hyperlink to task>


2. Document ALL the steps required from the first screen to the last.

The advantage of the first approach is that it considerably lowers the
maintenance and the size of the Help project. The problem is that the user
may end up "clicking backwards" several times, working their way from the
final task screen to the initial task screen, which is very cumbersome and
difficult. The user would have trouble getting a proper idea of ALL the
steps required to do the final task, from start to finish.

The advantage of the second approach is that it clearly shows the user how
to do the task from start to finish. But again the problem is that it
greatly enlarges the size of the Help document. Often there would be several
ways to do one of the preceding tasks. Since there were hundreds of tasks in
this project, it could lead exponentially to a document containing hundreds,
if not thousands of pages!

The solution I found was to use a mixed approach of these two. I documented
all the steps where possible, but occasionally I did use method 1. I tried
to keep the number of clicks to a minimum, though.

Has anyone had a similar experience? What was your solution?


Andrew T. Brooke
abrooke -at- pathcom -dot- com

Acrobat & FrameMaker Seminars: PDF Best Practices, FrameMaker-to-Acrobat
Advanced Techniques, FM Template Design, Single Sourcing with FrameMaker
in Brussels (Oct), and in Montreal & Dallas (Dec):

Check out the new release of RoboDemo, our easy-to-use tutorial software.
Plus, buy RoboHelp Office in August and save $100 with our mail-in rebate.
Get details and download free trial versions at

You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit for more resources and info.


Previous by Author: Re: Viva le Same! Linux
Next by Author: Managing your tech writing career
Previous by Thread: RE: eDocs, iTutor
Next by Thread: RE: Documenting complex tasks in Online Help

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

Sponsored Ads