What is an Error Message?

by Siobhan Walsh on June 21, 2015

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

Error Message Writing Guidelines

June 14, 2015

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…

Read the full article →

Sample Website Installation Plan

June 14, 2015

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…

Read the full article →

Release Notes: how to validate technical accuracy

June 12, 2015

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…

Read the full article →

IBM Error Message Guidelines

May 31, 2015

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…

Read the full article →

Release Notes: how to test technical accuracy

May 28, 2015

Q: 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…

Read the full article →

Configuration Guides: How To Document Parameters

May 28, 2015

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…

Read the full article →

Software Testing: how to keep Agile projects on track

May 22, 2015

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?…

Read the full article →

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

May 18, 2015

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.

  1. When – use if instead use when.

Read the full article →

Release Notes: 7 Steps to Better Enhancements

May 18, 2015

Want to improve the quality of the enhancements in your Release Notes? Here are seven ways.

Enhancement Identifier

Provide the reference number for the enhancement, such as Salesforce 12345.

Business value

Describe the benefit to the user if they use…

Read the full article →

Context Sensitive Help: 13 Ways to Test and Improve

May 16, 2015

After writing the Content Sensitive Help, create a test plan to check that the Help works correctly.

Before you start testing the Content Sensitive Help:

  • Clear the cache.
  • Open Excel to log errors.
  • Don’t test your own work.

Read the full article →

Technical Documents Reviews: Mentoring Indian Tech Writers

May 16, 2015

Does your technical writing team have offices in Bangalore?

Many US software companies are moving technical writing projects to India, Romania, Singapore and Poland.

I often help these teams setup their tech writing dept and mentor junior writers who are…

Read the full article →

How to write documents for SaaS web applications

May 14, 2015

SaaS and web-based applications are becoming more popular as they replace desktop or network installations. How you document them is mostly the same as documenting traditional but there are some difference. Let’s take a look.

  • Registration – explain how

Read the full article →

Technical Documents Reviews: How to Perform a ‘Post Mortem’

May 14, 2015

After every major release, do a post mortem of your technical documentation and look at how you can improve team morale, writing process, document reviews, and the documentation product.

Post-mortems focus on two areas

  • Quantitative data — such as,

Read the full article →

Installation Guide Checklist: Sample Template For Technical Writers

May 14, 2015

In the introduction section, identity the software you are about to install, steps to prepare for installation, running installation scripts, and post-installation tasks after the installation script has completed.

In general, your installation guide will include most of the following:…

Read the full article →