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.
Dave Stewart wonders: <<For the software I currently document, the engineers
have written a large number of error messages that appear when a user
performs a task incorrectly.>>
A quick aside before I answer your question: Ever noticed how nobody ever
writes problem-solving messages? Under the category of "what's in a name?",
I suspect many of the usability problems related to computing arise from
this nomenclature; if you name something an error, inherent in the name is
the likelihood that all you're going to do is report the problem. Call it a
"solution" message and suddenly you're thinking in a whole new way: about
helping someone solve the problem. Isn't it time we started helping the
programmers write solution messages?
<<We've received feedback from customers that the error messages are not
descriptive enough, and we're working on making the messages more
comprehensible so users know exactly what went wrong and how to fix the
problem.>>
That's the way we as a profession should be heading with "error" messages.
Congratulations on starting to do so, and good luck taking this approach as
far as it needs to be taken.
<<I'm wondering if anyone has ever included an appendix in their
documentation listing each error message in the source code, along with more
extensive descriptions of the solutions to each problem?>>
I've been trying with moderate success to persuade our programmers to create
more useful error messages that actually explain the problem and recommend
what to do about it (including "we don't know what caused this, but if you
call us with details, we'll try to fix the bug"*). It's a major change in
mindset, and difficult to achieve. In the meantime, documenting error
messages in a manner that actually lets users do something about the problem
rather than simply calling technical support is a great transitional step.
* A loose and irreverent paraphrase. Some errors may arise from innumerable
causes, and documenting all the causes can be a nightmare. Sometimes it's
just more feasible to write something simple and general than an entire
treatise on the software's innards.
--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html
"Any sufficiently advanced technology is indistinguishable from a
personality, and an obnoxious one at that."-Kim Roper
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Collect Royalties, Not Rejection Letters! Tell us your rejection story when you
submit your manuscript to iUniverse Nov. 6 -Dec. 15 and get five free copies of
your book. What are you waiting for? http://www.iuniverse.com/media/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.
