Re: Need suggestions for documenting err

["Mutton, Sara" <s -dot- mutton -at- TECHSMITH -dot- COM>]

Well, thank-god for the help button, eh?

First, there is no good fix for the situation you are facing.  I am the
resident
fuss budget at a company which just, very recently, assigned me the same
task.

I tried to do it.  I gave them a mock up.  Pointed out the flaw in their
logic ie.
Stupid messages are still Stupid message, even with help -- and they laughed
at me until the customers started saying the same thing.  Our company makes
a very complex product which is seen and used mostly by network adminstrator
types -- but technobabble doesn't seem to go over well with even that
sophisticated
an audience.  We are in the process of redesign the whole interface now....

The real solution is too say right up front that the messages should be
changed
and that help is not a fix for bad design.  If you do, at least the
management can't
come back and say that your help did not make the product more useable and
that
it's YOUR fault that's so.  Saves one neck in a crunch.  And there will be
one.

You also might start collecting material on how to write error messages and
GUIs and dropping them conspiciouslyon the keyboards of developers when they

are away from their desks.  One very good article by Noah Davids, "10
Principles
for Supportable Application Designs" in the OCT/NOV issue of PC Techniques.

From there and for the moment, you might try defining the message in help
before
your explain the solution:

eg.  if the message says, "Stand on your and drink water: your hard drive
just crashed."

then say,  "the message is asking you to calm yourself by standing your head
and
drinking water.  Since this dangerous act requires great concentration, it
will take
your mind off the fact that our product just caused your hard drive to eat
itself.  If
you still find yourself distracted, do it on the windowledge."  (Definition
of the message.)

To fix the problem, do calm yourself, and then go out and buy a new hard
drive, etc..."
(What to do to fix it.)

As usual, you'll have to make your language simple and the design of the
help screen
consistent.  If I think of anything else, I'll pipe up.

Sara
 ----------
From: The Tech Writer
To: Multiple recipients of list TEC
Subject: Need suggestions for documenting errors
Date: Friday, October 13, 1995 3:02PM



From: The Tech Writer <techwrtr -at- CRL -dot- COM>
Subject:      Need suggestions for documenting errors & warnings
Comments: To: Tech Writing Mailing List <TECHWR-L -at- VM1 -dot- ucc -dot- okstate -dot- edu>
To: Multiple recipients of list TECHWR-L <TECHWR-L -at- VM1 -dot- ucc -dot- okstate -dot- edu>

I have been given the project of creating a help file for our version 1.0
software's core dialogs (those that are shared by the different apps in
our suite), warnings, and errors.

The goal? To take those cryptic messages that supposedly tell you what
went wrong, and expand upon them to make them truly helpful.

The problem? We're under a deadline for the 20th (next Friday), and the
one person who can tell me what all of the messages mean is a crucial
person for many other parts of the project. I need suggestions on how to
figure out what the errors mean, and how I should go about putting
something short but meaningful together.

Thanks in advance for any help you can give,

 -David Castro
 techwrtr -at- crl -dot- com
 http://www.crl.com/~techwrtr/


Sara Jane Mutton
Technical Writer
Techsmith Corporation
3001 Coolidge Road, Suite 400
East Lansing, MI 48823 USA
s -dot- mutton -at- techsmith -dot- com
http://www.TechSmith.com/
Voicemail: (517) 333-2100x168
FAX       :  (517) 333-1888