Posted on

Review Checklist for Technical Documents

teechnical-documents-review-checklist

Making a list, checking it twice…

How do you review your technical documents? You just don’t eyeball them, right?

Before you send your shiny new user guide into the wild, use the following checklist to review your technical documents:

Title

Is the title consistent across all documents? Note lower, mixed, and upper case combinations

Product name

Is the name of products consistent?

Branding

Does the document adhere to the company style guide?

Strapline

Is the strapline consistent?

Logo

Is the same logo used on all documents?

Cover sheet

Check legacy documents or documents created with a rogue template

Version

Is the same version number used on all documents?

File Properties

If writers use File, Save As to create a new document, the ‘old’ file properties must be updated

Table of Contents

Has it been updated? Have rogue sections crept in?

Language

Are UK and US English used in the same document?

Should

Don’t write what might happen next. Explain what to do right now when you’re performing the procedure.

Instead of:

The command should be run if a new product is installed.

Write:

If this product is installed, run this command.

Will

Don’t write what will happen, say what is happening now.

Incorrect

This will create the following files in the Bin subdirectory.

Correct

This creates the following files in the Bin subdirectory:

Start with Verbs

Incorrect

The folder located on the D:\ drive should be copied from the server.

Correct

Copy the folder located on the D:\ drive from the server

Screenshots

Add a caption and explain what’s happening in the screenshot.

Don’t assume the reader understands what’s happening in the screenshot.

Within v in

Don’t say the chapters within the document.

Within specifies a time frame, for example, within 3 days.

Prerequisites

List prerequisites in the correct order.

If you have to install prerequisites in a specific order, use a numbered list. Add warnings, cautions, and recommendations.

Upgrade

In the Upgrade section describe:

  • New install — how to install from scratch, a clean install.
  • Upgrade — how to upgrade an existing installation.
  • Uninstall — how to remove the application from your system. Include any recommendations or warning before they start.

Repeated phrases

For example, if you say that you need to perform the following steps as an Administrator in the first sentence, you don’t need to mention it again.

Incorrect

To install the server, perform the following steps as an Administrator:

Open the Command Prompt as an Administrator.

Correct

To install the server, perform the following steps as an Administrator:

Open the Command Prompt.

Posted on

User Guide Checklist

This checklist summarizes the recommended structure and contents for User Guide documents.

teacher

Introduction

In this section, introduce the User Guide and cover the following areas:

– Intended readers – identify the different user types, for example, system operators, home users, and experts. For each, identify the assumed level of experience and highlight the sections of user guide which apply to them.

– Software version – identify the software release the User Guide refers to.

– Purpose – describe the purpose of both the system and User Guide.

– How to use User Guide document – describe the intended use, section contents and relationship between sections.

– Related documents – identify any related documents.

– Conventions – describe symbols, conventions and syntax conventions used in the guide.

– Problem reporting instructions – provide an email address so readers can contact you if they find an error or omission.

Overview

Outline how the system works at a high level.

– Identify the key functions

– Inputs and Outputs – identify inputs what you, the reader, need to enter, and outputs, what you expect in response, for example, reports.

– Provide further detailed explanation, if necessary.

– Assumptions on user expertise, for example, experience or proficiency in related areas or previous training.

Procedures

This is usually the heart of the user guide. For each task, document the following:

– Explain how to get started, for example, specific settings they need to make to use the application, such as installing a plugin or checking that a specific version of Java has been installed.

– Describe the different functions of the system.

– Provide cautions, warnings, and recommendations.

– For each procedures, identify where in the application you perform this task, input operations and expected results. If necessary, include a screenshot that helps the reader understand the task. Avoid pointless eye candy screenshots.

– Required parameters, optional parameters, default options and order/syntax

– Provide examples

– Identify known issue, likely errors, possible causes, and resolutions.

Reference

Identify and describe all system capabilities, for example,

– Describe the purpose of different buttons on the menu bars, what happens if they get greyed-out, how to change this, why this occurred, and how to reset window layout.

– Describe the purpose of each field, identify mandatory settings, minimum or maximum settings, recommendations, and data input types.

Error Messages and Recovery Procedures

– Document all error messages.

– Identify root cause.

– Suggest recovery procedures

Glossary

Provide list of ambiguous terms or terms users may not know to the reader.

Index

This is recommended for any User Guides of 40 pages or more.

Document Control

Ensure there is Document Control, Sign-off and Change Record information.

Document Structure

Ensure that the guide has the following:

– Headers, footers, navigation bars

– Table of contents

– Index

– Glossary with product terminology and industry terms

– Cross-references/links to related procedures/documents

– Is each topic self-contained? In other words, can you perform the task from start to finish without having to go to another page?

– Is there adequate white space?

– Have you avoided large blocks of text?

– Does the document separate conceptual, procedures, and reference materials?

Visual Information

In addition to text information, provide visual cues to help the reader use the manual, understand concepts, and help them digest information faster.

You can achieve this by using some of the following:

– Headings

– Bullets

– Bold

– Arrows

– Illustrations

Different Learning Styles

Where possible, develop content that supports the following methods of learning:

– Visual

– Audio

– Touch

In addition, provide the following types of examples:

– Concrete examples

– Abstract concepts

Document Format

Produce the user guide in a file format the suits the reader. For example, do they want the document in PDF or as Online Help or both?

Other factors to consider include:

– Size – remember to optimize the PDF before publishing.

– Online/print – prepare the document in both formats if necessary.

– Software/hardware environment – will the reader need any special software to view the documents?

– Binding – if delivering a hardcopy, make sure the binding is reliable, so pages don;t fall out after a little use.

– Coating – if the document will be used outdoors, make sure it is weather-proof.

Posted on 2 Comments

Writing Technical Documentation for Japanese Readers

Carsten Mende explains how loan words are used in China and Japan. These are English words that are commonly used in everyday Chinese, (i.e. loaned) but may not translate correctly if taken literally. He looks at how the ‘Chinese and Japanese languages incorporate English terms and how they are used’ and gives suggestions on what to avoid when translating documentation into these languages.

Difference between English, Chinese and Japanese syllables

He starts by showing the different between how syllables are created in these languages. And as someone who has studied Chinese for a few years, it’s both fascinating and frustrating. Oranges and apples, so to speak.

Latin – allows ‘numerous variations for combining letters and the amount of syllables is extremely large. English has more than 11,000 syllables.

Chinese and Japanese is very different: Chinese (Mandarin) is written in characters; each reflects a syllable and not a single letter.

Adopting loan words in Chinese and Japanese

He shows three mechanisms for the adaptation of English words in both languages:

  • Phonemic way
  • Semantic way
  • Adaptation without any transformation

For example: Coffee 咖啡 ka fei

Suggestions

He cautions that when translating or transferring into a foreign language, ‘even obvious things may shape up as something completely different. So you should always treat your customer attentively, take him seriously and be prepared to communicate in his mother tongue.’

Read Carsten Mende here

Opportunities

The quality of technical documentation in China is often very poor. It’s not for lack of trying, rather they lack experience technical writers and have had little exposure to international audiences.

For foreigners this represents a huge opportunity. Technical writers who can come to China and test the waters could do very well. The pay is increasing all the time and the cost of living significantly lower than elsewhere.

Fancy moving?

Posted on 15 Comments

User Guide vs User Manual – which is right?

Let’s say you’re setting up a new Tech Docs Dept.

You need to create new guidelines, style guides and naming conventions.

Should you call the user ‘documents’ User Guides or User Manuals?

Which one is right?

I was asked this question by a colleague in India who is setting up a Technical Publishing Dept in Bangalore.  He wants to go with user guide—me too, actually.

  1. When I worked in the UK, it was (mostly) referred to as a User Manual.
  2. Whereas in the US, it was a User Guide. I think the Americans (and me!) like things to be short and to the point. Guide is just that little bit quicker to write, especially when you’re creating MS  Word templates.

Saying that, there is no right and wrong, but I did a little fact finding first.

What Google says about User Guides

I searched Google and came up with these results.

  • 15,600,000 for “user guide”
  • 10,700,000 for “user manual”
  • 5,210,000 for “user’s guide”

What surprised me here was that User’s Guide was so widely used. I’ve always found this a bit annoying. I just don’t like apostrophes, I guess.

Top 5 Most Popular User Guides

A quick check on the most popular user guides showed the following. Not what I expected.

IBM Technical Documents

Next, I checked IBM and Microsoft  to see what term they used.

  • 15,324 for user guide
  • 1,047 for user manual

So, they prefer user guide. Though, you’d think they’d make this mandatory. Of course, it’s not easy when you have offices in every corner of the world, so let’s cut them some slack.

Microsoft prefers User Guides too

The folks are Redmond were more consistent with

  • 1.8 million for User Guides and only
  • 73k for User Manuals

And, to be fair, many of the user manuals were actually guides when I checked. Someone check that search engine!

Is Apple different?

Yes, of course.

Apple prefers the term User’s Guide. Like I said, I never bought into this. I prefer short, snappy titles. We don’t call them System Administrator’s Guide, do we?

Well, of course, some do.

Things to consider when naming your documents

  • Avoid obscure or unique terms for your documents. Use industry standard terminology.
  • Ask your target audience what they expect.
  • Create a Style Guide or adopt one, e.g. the Microsoft or IBM style guide.
  • Develop a naming convention, e.g. a structure approach so that all documents are named, filed, and indexed correctly.
  • Develop a numbering convention. Show people how to number documents, for example, when to go from 1.1  to 1.2 and when to go from 1.2 to 2.0.
  • Be consistent.
  • Be patient when they get it wrong.

My career really began to take off when I saw myself as an ‘enabler’ rather than a writer. My identity of who I was changed from a guy who cranked out docs to someone who helps others get their projects done.

People want to learn, do your best to help them get there.

What do you think? What’s the most practical way to name documents and setup a new Technical Writing Dept?