Technical Writers describe error messages that appear within many documents and applications. They are useful, necessary, and required. Without these warning messages, readers\users would not know that, e.g., an incorrect key was pressed or that some information was missing to complete a task. Error messages describe what to do (or not), what information is required, or whom to contact to correct a situation.
Error messages exist within documents, such as:
- Technical Specifications which developers use to program and present different types of error messages indicating where, when, how, and what.
- Functional Specifications which describe expected error prompts and information required to complete tasks.
- User Guides which warn users by defining errors (what to expect – where and when) if certain prohibited tasks are done and how to correct the problem.
- Ready Reference sheets which list commands as well as what errors might occur, what they indicate, whom to notify, and how to correct certain problems.
- Test Plans which help locate problem areas.
- Bug lists (or List of Errors form) which contain anomalies from testing. e.g., while performing software testing to identify defects, flaws, and errors in application codes, the detailed steps that led to the errors are noted here. Without this completed form, developers would not be able to replicate the occurrence and hence correct it.
- Feedback forms which include questions such as ‘Who is not satisfied with the document and Why’. Asking appropriate questions help to find problem areas, e.g., material was written for the wrong audience, contains incorrect or bad formats, or has errors.
To prevent errors within a document:
- The front matter of certain documents should present a list of readers/checkers approving the document, thereby ensuring its completeness and accuracy. This will avoid problem areas, i.e., missing tasks within an application, missing reports, incorrect data, etc.
- The material should be produced as a technically accurate document.
- The contents of global documents should be examined and presented as a clear, concise, error free
- The writer should be vigilant and, put themselves in the shoes of the reader, and maintain direct communication with stakeholders.
Error messages are also written for:
- Developers to ensure that accurate data is located, gathered, and present a clear understanding of data repositories.
- Disclaimers to avoid liability for errors or omissions.
- Data analysts to investigate data discrepancies and to detect and resolve errors.
Benefit of Errors:
- They help to teach, especially when using animation to display problems and resolutions.
- They help to maintain and manage accurate data.
- They help to provide editing and proofreading for grammatical errors.
The Technical Writer must ensure accuracy, completeness of technical documentation, and meet company standards, even when providing error messages. Technical Writers are also editors when ensuring documentation that is error free in content and in the usage of grammar, spelling, etc. This is especially important when producing material (i.e., marketing, training, global, or compliance documents) that reflect upon a company’s image.
Gail Zack Anderson, President of Applause, Inc., has nearly 20 years experience in training and coaching. She
provides individual presentation coaching, and leads effective presentation workshops and effective trainer workshops.
Theresa Pojuner is a Documentation Specialist with over 20 years of writing experience and is skilled in many areas of documentation, for example, Style Guides, Training Manuals and Test Cases, wth a specialty n Technical Writing and Procedures.