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:Writing error messages From:"Less is more." <yvonne -at- SATURN -dot- SMARTSTAR -dot- COM> Date:Fri, 17 Jun 1994 08:58:05 -0700
Tina Sansom writes:
>Thought I'd throw my oar in here. I write error messages, because the
>programmers aren't allowed to! What a deal. They write cryptic little codes
>which refer to specific error contitions in specific places in the application,
>and I cross-reference the codes to a file full of error message text that I
>write and own. It's been great, because lots of people come to me with
>suggestions and ideas and thoughts, who don't like to write. I can take it
>all in, but I own the message file as if it were one of my own documents.
I agree that this is the way it should work if possible. We have a database
that stores the message codes, text, and descriptions for the online and
printed information about the errors.
The programmers discuss message wording with me and I rewrite them as needed.
Then I write the detailed information for the manuals. Since the files used
in the product, online help, and documentation get built from this application,
I can change things even at the last minute. (Well, the next-to-last day
actually.)
A couple things I've found:
Our messages can include context-based information, like the line the error
is on or the object that caused the error. Our programmers seem to like to
omit these things -- they require a bit more work. I have to encourage them
to include the bits that make errors useful by knowing enough about the
internals of the product to know what information they can probably include.
I have to watch the message codes in addition to the message text. One
programmer tried to get away with a message code of:
SQL-W-DICTOOLONG, Dictionary name cannot be longer than 31 characters.
Yvonne DeGraw
yvonne -at- smartstar -dot- com
SmartStar Corp
Santa Barbara, CA
