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.
> I'm curious as to what the most common practice is when time
> comes to list error messages that can be returned by a method.
>
> Do you guys list error messages for each method, even if they
> are repetitive, or do you have a section with all possible
> messages and ways to solve problems?
I document errors for something similar. We have components that produce
alerts. An alert may resemble the following:
"Message text: 'User defined:Stored Procedure execution failed, system
will try again. Error executing: exec p_egtVolatileData DB error:
ODBC-40001-1205-Microsoft-ODBC SQL Server Driver-SQL Server-Your transaction
(process ID #24) was deadlocked with another process and has been chosen as
the deadlock victim. Rerun your transaction.
DART-62-DGDB_X_conn_sql_select-volatiledata-unable to execute SQL statement
// 40511 // ....."
I have a form that includes various fields, then the message, then sections
for explanation, reason, fix, and prevention. I also include, in the error
form, all other components that can generate the same type of alert.
I create the form, then save it as two versions; one, under each component
that can cause this (ewVOLATILEDATA_FROM_WEB), and one, where I use some or
all of the text immediately after User Defined (Stored Procedure execution
failed, system will try again. Error executing: exec p_egtVolatileData DB
error:...)
In this way, they can locate all alerts for a particular component, or all
components that can generate the same type of alert.
I deliver by PDF. They can look down the bookmark list for all alerts that
the component can issue, or for the specific alert and determine which
component caused it.
it works around here.
John Posada, Senior Technical Writer
Barnes&Noble.com
Moderator: Yahoo "Techwriter" group http://groups.yahoo.com/group/techwriter/
"If you're afraid to be second-guessed, you better not make any decisions."
--Hal Sutton, America's 2004 Ryder Cup Captain
