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

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 →

How to write Enhancements for Release Notes

May 12, 2015

What do you need to include in your enhancement release notes?

At a minimum, you need to cover the following:

  1. Description – identify the new enhancement. Avoid the words new, enhancement, or feature in the title. You can drop

Read the full article →

Sample Text for Writing Release Notes Enhancements

May 12, 2015

An enhancement is a new feature, or an improvement to a current feature, included in the current release.

To help the reader understand the enhancement, describe:

  • Where the enhancement is located in the user interface.
  • What parameters need to

Read the full article →

Release Notes – How to Write ‘Known Issues’

May 10, 2015

This week we look at how to document known issues in release notes.

The Release Notes web page on the NuGet site offers good examples of how to document known issues in release notes.

We’re going to look at three…

Read the full article →

Release Notes: 13 Mistakes to Avoid

May 8, 2015

It’s easy to overlook the importance of release notes.

But when customers want to know exactly what a specific parameter does, it’s the release notes that often turn too.


Remember, for very large document sets, it can hard to…

Read the full article →

Difference Between SOPs v Work Instructions v Procedures

May 31, 2014

How can you tell if a document is a SOP, Procedure, or Work Instruction? Also, what are the connections between each of these documents? Is one more important than the other? Do you need to write an SOP before the…

Read the full article →

How to Write a Better System Administration Guide

May 27, 2014

What do System Administration Guides and Mozart have in common? There’s a scene in the movie Amadeus where the Emperor asks Mozart to take out the boring notes. He found it too long.

“Cut out some parts here and there.”…

Read the full article →

Operations Plan: The Definitive Guide

October 12, 2011

Want to write an Operations Guide? This tutorial explains how to write your first operations manual. It helps you get started, suggests how to format the document, create the table of contents and what else…

Read the full article →