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.
Subject:Re: Need suggestions for documenting err From:"Mutton, Sara" <s -dot- mutton -at- TECHSMITH -dot- COM> Date:Fri, 13 Oct 1995 15:40:53 -0600
Well, thank-god for the help button, eh?
First, there is no good fix for the situation you are facing. I am the
fuss budget at a company which just, very recently, assigned me the same
I tried to do it. I gave them a mock up. Pointed out the flaw in their
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
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
and that help is not a fix for bad design. If you do, at least the
come back and say that your help did not make the product more useable and
it's YOUR fault that's so. Saves one neck in a crunch. And there will be
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
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
your explain the solution:
eg. if the message says, "Stand on your and drink water: your hard drive
then say, "the message is asking you to calm yourself by standing your head
drinking water. Since this dangerous act requires great concentration, it
your mind off the fact that our product just caused your hard drive to eat
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
(What to do to fix it.)
As usual, you'll have to make your language simple and the design of the
consistent. If I think of anything else, I'll pipe up.
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.
Sara Jane Mutton
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