11 Examples of Stunning REST API Documentation

Looking for examples of API documentation online? Wondering how the big boys write their API documentation so you can get a little inspiration? Me too. //Get the REST API Documentation Tutorial here We’ve being writing a lot of API documents recently for a new client. She asked for examples of how other IT companies publish […]

21 API Document Generation Tools You Might Have Missed

Want to document your Web and RESTful APIs but don’t know where to start? Me too.  APIs are great but they also need documentation. I did a bit of hunting and compiled this list. It’s in no particular order of preference. I sorted them A-Z. [Get the API Documentation Template here] 21 API Documentation Tools […]

NEW – Quality Assurance Plan Templates (MS Word + Excel)

This week we created a new set of Quality Assurance Plan Templates. I sat templates as we developed more than just the MS Word template, but sample materials, and also seven pretty slick Excel spreadsheets. If you’re involved in tech writing or software testing, I think these templates will be of real value to your Quality […]

Microsoft Error Message Guidelines

When you write messages, follow these guidelines: · Avoid vague wording. Give specific names and locations of the objects involved. · Avoid “please.” It can be interpreted to mean that a required action is optional. · Do not refer to implementation details that are invisible to the user. For example, do not refer to the […]

Error Messages: Do’s and Don’ts

Do’s and Don’ts when writing error messages: Don’t · Avoid the word “bad”. Use more descriptive terms to tell the user what is wrong. For example, avoid messages such as “Bad size”. Instead, tell the user what criteria to use when specifying a size. · Avoid the word “please”. It can be interpreted to mean […]

How to Write Error Messages

How to Write Error Messages Error Message Template – Download Now! Here’s a suggested approach to writing error messages: · Create a spreadsheet. · Give each error a number so you can track them. · Add columns for the error message and the root cause. · Establish an error message quality-control team. · Create simple […]

[How to] Write a Customization Guide

The first question is: who are you writing this customisation guide for? As a technical writer, the skill to developing a useful guide is to keep the reader in mind. Who will be reading this customisation guide? What’s the most important thing they need to know? How can I make this more helpful to them? […]

Error Messages: Mistakes to Avoid

Try to avoid the following: Anthropomorphize. Don’t suggest the software has feelings or thoughts, for example, the PC died. Instead, say, it stopped responding or is not available. Blame. Maybe the user was at fault, for example, entered text into a field meant for numbers. However, instead of saying this was wrong, bad, or illegal, […]

The Definitive Guide to Writing Error Messages

These guidelines will help you write error messages that are easy to update and useful for customers. Error messages are the first line of customer support. Poorly written error messages increase technical support costs. A well-written error message tells you, the user, the following: What has happened Why has it occurred How it impacts you, […]

User Guide Checklist

Use this checklist to write your User Guide. The checklist will help reviewers determine if the specifications meet the quality criteria and comply with development methodology requirements. Download 4 MS Word User Guide Templates General Information System Overview – introduce the system at a high-level and its relationship to others, if necessary. References – list […]