Re: How do you document error messages?
Our organization desperately needs to provide our users & support staff
with more info about the error messages that our various products produce.
I'd appreciate anything you could share about how your organization
handles this as well as what kind of information you document.
Mary,
This is a collection of ideas distilled from postings by various people over the years.
1.
What you ideally want to present, at least to your support personnel if not to your users, is a table for each of your products, they run independently of each other, or a master table, if all your products are really a single integrated system, that is organized by error message number.
If your errors don't identify themselves with a visible number or unique name in the user interface, you've got other problems--see below.
The table should have columns for the identifier; the message text, including tokens for any variables; an explanation of the possible cause or causes (in separate table rows) and of the significance of the tokens; and any corrective action that can be taken.
The best place for such a table is in a live database that drives your technical support operation rather than a printed manual, by the way.
2.
You need to lobby your development manager to push the writing of the error messages back to the design stage rather than the coding stage, and that tech writers should be reviewing the design documents specifically to edit any text strings that get presented to the user, whether on the page/screen or in popups and error messages.
To make your case, see if you can get a friendly developer (cookies help) to extract all the text strings from some single module. These should be printed out for you as code snippets, each one identified by source filename and line number, so they are traceable back to the source. Take a red pen and mark up these pages, in copy editing mode. Be thorough and bleed all over the pages, but be neat. Use this exhibit when you approach the development manager, positioning it as a demonstration of why a writer should be involved.
Another point to stress is that thinking about error conditions and error messages during the design phase will tend to make the software more robust in the first place.
3.
Schedule a meeting with your software architect to talk about pushing all user-visible text strings of any kind into something you have access to for editing purposes. The exact way this is implemented depends on the development environment, which is why the architect has to be involved; but point out that doing it this way paves the way for future internationalization and localization of the software; so it's a good thing to do.
4.
You can only control what you can control. If the operating system is generating and displaying error messages outside the control of your software, it's not really your job to document those.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
ROBOHELP X5: Featuring Word 2003 support, Content Management, Multi-Author
support, PDF and XML support and much more!
TRY IT TODAY at http://www.macromedia.com/go/techwrl
WEBWORKS FINALDRAFT: New! Document review system for Word and FrameMaker
authors. Automatic browser-based drafts with unlimited reviewers. Full
online discussions -- no Web server needed! http://www.webworks.com/techwr-l
---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.
Previous by Author:
Re: Allocated chapter numbers for specific chapter content
Next by Author:
Re: ADMIN: TECHWR-L's Next Steps (Part II)
Previous by Thread:
How do you document error messages?
Next by Thread:
Re: How do you document error messages?
Search our Technical Writing Archives & Magazine
Visit TechWhirl's Other Sites
Sponsored Ads