Tips for creating useful technical documentation and job aides

In many technical industries there is increasing pressure to document processes and procedures to streamline operations. I’ve heard these documents called many different names such as job aides, MOPs (Methods of procedures), SOPs (Standard operating procedures) or more simply KB (knowledgebase) articles.  This post will outline the most effective tips for creating effective technical documentation for use in your organization.

Clear and concise titles

This is probably the most crucial item.  In a few words, the title should define the outcome and what it applies to.  Try not to be too broad and not too precise; In the words of the little red riding hood, find one that’s “just right.”

  • Example of an overly broad title: How to reset my phone
  • Example of an overly precise title: How to factory reset my Cisco 7940 IP phone using the dialpad on SIP firmware 03-08-00
  • Example of a “just right” title: How to factory reset my Cisco 7940 IP phone

Details of the hardware/software

List the manufacturer/vendor, all products (model number/software name) this job aide applies to and all versions/firmware this job aide will work with. For good house keeping, I try to include a picture of a device (front and back) for reference.

  • Manufacturer/Vendor: Microsoft
  • Product: Microsoft Outlook
  • Version: Outlook 2003, Outlook 2007, Outlook 2010

Describe the summary of the article

In a few sentences, describe the generalities of what will be performed and who will be doing what.  It is particularly important to identify (and write for) the audience.  Organizations that have end-users and technicians will need to pay special attention to this.

  • Example of an effective summary: This article will assist a technician or end-user with performing a factory reset of the Cisco Systems 7940 IP Phone.  The end result will erase all local and network-provided configurations and restore the phone to a default configuration.

The detailed process

The process is the most important part – it defines exactly how to accomplish the end result listed in the summary. The details area can (and should) have some very specific areas which should be inserted where necessary/relevant:

Prerequisites

A VERY important are to list specific conditions that must be met in order to perform the tasks provided.

  • Example: You must be physically present to perform this action.
  • Example: You must have power user (or higher) access to perform this action.

Process

NEVER write in a story or narrative! The consumer of this document is here because they have a specific task and want to complete it efficiently. Numbered lists are your friends! Write specific steps, bolding certain aspects/keywords you feel may be important for the consumer of the document.

Example:

  1. Click the Start Button/Icon.
  2. Select Control Panel.
  3. Select Programs and Features.

Notes

This section should be used for commentary on unusual or notable events, conditions or results that may have occurred (either expected or unexpected).  This is your area to write a note to the next person on any “gotcha’s” that may have happened.

  • Example: Once the factory reset has been performed, the phone will attempt to obtain configuration parameters via DHCP Option 66. To ensure a clean factory reset, it is recommended to perform this procedure on a network without a TFTP configuration server or DHCP Option 66.

Article Properties

This section of information is more for housekeeping and ease of access.  It should contain relevant information on the document:

Example:

  • How to access it (URL/permalink)
  • How it’s organized (Category/tags)
  • When it was originally published
  • When it was last updated

Searchability

Depending on your knowledgebase or wiki, ensure full-text searching is on and working.  You want people to be able to search easy phrases/terms and see relevant results.

Depending on how/where you host your knowledge, you may opt to chose for a public and internal view so that internal-only documents are only seen by employees.

Keep your content relevant

If you choose to avoid using software/version associations in your document, you’ll need an internal process to refresh your documentation as things change over time.

  • Example: If you wrote an article on “How to open a document from a network location in Microsoft Excel” the steps (details section) would change dramatically for Office 2003, 2007, 2010 and 2013.