Oracle Error Message Guidelines

The following is an example of how Oracle writes error messages. Notice the format of the error message: · ORA-00058 – error number for tracking · DB_BLOCK_SIZE must be string to mount this database (not string) – description of error message · Cause: what caused the error to occur · Potential reasons: note the use […]

What is an Error Message?

Q: What is an error message? An error message describes a problem that stop a user or system from completing a task. An error message must include enough information for the user to solve the problem. What types of error messages are there? In general, there are three types of error messages: · Confirmations · […]

Error Message Writing Guidelines

Error messages should: Be helpful: explain how to fix the problem, avoid repeating it again, and saving any data you’ve entered, if possible Be specific: focus on one issue. Avoid general statements. Be precise: describe the issue in words I, the user, can understand. Educate: most users only read Help and tech docs when all […]

Sample Website Installation Plan

The following guidelines explain how to install a website application. Getting Started It is recommended that you install and verify the software in your test environment prior to deploying it to your production environment. Warning – When specifying an existing database as the installation target, this install process will replace that existing database. Be sure […]

Release Notes: how to validate technical accuracy

You can validate the accuracy of your release note by creating a checklist and reviewing each item on the list until you know these by heart: Files affected Have you entered the files for its related product? For example, some DLLs may affect one version but not another. Make sure these are not entered by […]

IBM Error Message Guidelines

The following is an example of how IBM writes error messages. Notice the words and phrasing as well as how the alert categories are explained. Error Message There is no value specified for the User ID. Explanation You must specify a value for the user ID. Alert Category Similar events are grouped in categories. The […]

Release Notes: how to test technical accuracy

Grasshopper, what do you after you’ve written your release notes? Test it. Here are four ways to check if the bugs, issues and enhancements are written correctly: 1. Can you reproduce the issue? Have you reproduced the issue on a local machine? Note that you’ll need the same version of the application that the bug […]

Configuration Guides: How To Document Parameters

If you want your customers to keep using your products, make sure every parameter settings is correctly documented. So, how can you write glittering configuration guides that sparkle and amaze when customers print out the PDF? Here’s how, grasshopper. Make sure to capture the following when documenting every parameters in your technical documents. No excuses, […]

Software Testing: how to keep Agile projects on track

Is Agile software development good for a tester’s mental health? Depends, doesn’t it? So, how can we keep software testing projects on track when the Developers are using Agile to create sprints? What do we need to ask our developers? Ask Dev to confirm THEIR understanding of UAT It’s not enough to ask, ‘do you […]

[Checklist] Release Notes: 7 Don’ts and 13 Do’s

If your technical writing job involves writing release notes, create checklists for writing, reviewing, and production. Use the following checklist to review release notes. Avoid the following mistakes when writing release notes. When – use if instead use when. The difference between when and if is that when implies something has occurred, for example, when […]