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.
John,
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
designed.
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.
Lisa
-----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
Posada
Sent: Saturday, March 16, 2002 11:43 AM
To: TECHWR-L
Subject: Documenting "touchy" applications
<snip>
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
time.
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.
www.ehelp.com/techwr
---
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 http://www.raycomm.com/techwhirl/ for more resources and info.
