RE: Documenting "touchy" applications

Subject: RE: Documenting "touchy" applications
From: "Lisa Wright" <liwright -at- earthlink -dot- net>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Sun, 17 Mar 2002 10:40:46 -0800

Couple of thoughts. First, do/can the error messages also direct the
user to where they *can* run the script correctly? Telling them they
CAN'T do something here is only helpful if the message also direct them
to where they can.

Second, in the materials themselves, I'd probably say something similar
to what you wrote to us. "The procedure for running this script must be
followed very carefully, or you may not get the result you want. You
will also see this script in other areas of the application, such as XYZ
view; however, it will not run correctly." If there are places in the
documentation where the user could be led to think they can do
something, but they actually can't, perhaps a gentle reminder would not
be inappropriate.

This type of instruction gives the reader a way to recognize and avoid
errors (i.e., running from the wrong view, if it's possible to
distinguish). I think it's part of our job to help users recognize
(i.e., learn) how to avoid pitfalls, particularly when poor system
design makes it easier for users to make mistakes. Any system that
displays a script in a place where you can't actually run it is poorly

I realize it's probably unlikely, but is there any way to get the
programmers to implement the scripts in such a way that they only show
up where they can be run correctly? You have a good relationship with
them. Perhaps they'd listen if you pointed out that it's clunky? I had
good success with this recently. The programmer had taken the easy
coding route, and the result was an incredibly complicated series of
steps for something that should've been very simple. I said, "gosh, I'm
just trying to think how I'm going to explain that." He went back and
recoded it and now it's a piece of cake. Granted, it's not as
complicated a program as a Siebel system. Still, it might be worth a
shot. YMMV.


-----Original Message-----
From: bounce-techwr-l-53104 -at- lists -dot- raycomm -dot- com
[mailto:bounce-techwr-l-53104 -at- lists -dot- raycomm -dot- com] On Behalf Of John
Sent: Saturday, March 16, 2002 11:43 AM
Subject: Documenting "touchy" applications
What's happeninig is that my documentation is becoming half "What to
do", half "What not to do".

Not only that, but maybe I'm making the applications appear more complex
than it would be if the user did exactly the right thing at the right

Is there a balance..a middle of the road approach? How do you guys
handle this?

John Posada, Senior Technical Writer

Check it out! Get some cool freebies when you buy RoboHelp! You'll receive
SnagIt screen capture software and a 10% discount voucher for RoboHelp
Consulting. This special offers expires March 29, 2002.
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.

Documenting "touchy" applications: From: John Posada

Previous by Author: RE: Occupational hazard - carpal tunnel
Next by Author: RE: Some thoughts on knowledge management, content management and single sourcing
Previous by Thread: Documenting "touchy" applications
Next by Thread: Re: Some thoughts on knowledge management, content management and single sourcing

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

Sponsored Ads