how to write a good installation guide

An installation guide is written to describe the installation of either a mechanical/electronics system (like a child’s swing or a hi-fi set) or a software product. Here we will focus mainly on the latter.

A software installation guide overlaps with System Administration Guide since it covers similar configuration tasks. That’s the reason why the demarcation line between these two guides may not always be very clear.

Here are the main components of a typical software installation guide:

1) System Requirements (or Prerequisites)

What kind of hardware, software and/or firmware are needed to install this software? Will it work if your Operating System is a Mac OS X, or Windows Vista? How fast your processor should be?

For example here are the system requirements for Windows VISTA OS Home Basic Edition which should be included in a Windows VISTA Installation Guide:

• 1 GHz 32-bit (x86) or 64-bit (x64) processor
• 512 MB of system memory
• 20 GB hard drive with at least 15 GB of available space
• Support for DirectX 9 graphics and 32 MB of graphics memory
• DVD-ROM drive
• Audio Output
• Internet access

2) Overview of System or Product Features

What are the basic features, characteristics, of the software or product in question? Provide them in a list, or table.

For example, if this is an office telephone (communication) software, list how many lines the software supports; what kind of power it operates on; how many users and passwords it supports; what kind of database it needs; how many “zones” “partitions” or “configurations” it supports; how many “communication units” “telephones” or other similar hardware it accommodates; etc.

It is appropriate to include in this section also ways to CONTACT the company or the client service department in case there are any product, warranty, registration, etc. related questions.

Also in this section include any LEGAL disclaimers, disclosures, official government agency warnings, UL (or other official certification agency) requirements, registration information, etc.

3) Minimal Quick Start Configuration

This section sometimes is published as a separate “Quick Start” or “Quick Start-Up” guide as well.

Describe in this section how to set up “system time” by entering the correct values into the internal “system clock,” if any.

Explain how to identify and interpret any system or hardware codes, serial numbers, acronyms or abbreviations that the product comes with.

Include one or more charts or drawings (as appropriate) describing how to install the software (or the product). Show the correct wiring connections, if any. If any physical installation is involved, including a drawing of screwdrivers or other tools attaching the product properly by driving screws or rivets, etc.

Your customers will really appreciate this section of the Installation Guide since they would be able to set up the product and see it in action quickly and thus build up their confidence in the product. Once that confidence is established they can proceed to fine-tune the settings and adapt it for more refined and complicated tasks. But the research has shown that if the customers cannot quickly start to set up and operate a system their level of frustration builds up quickly, leading to a poor user experience. That’s why this section is important to encourage customer loyalty, build high satisfaction levels, and generate as few calls to the customer service department as possible.

4) Set-Up Configurations

Usually a software or a product will have a “typical” and an “exceptional” or “customer-designed” installation. This installation will sometimes be referred to in product literature as “deployment” as well.

Explain the most “typical” installation (or deployment) configurations that customers of this software or product have used in the past. If possible also tell your users which situations and which client goals justify which type of “typical installation.”

5) Maintenance and Error Messages and Troubleshooting

All software products and most electronic gadgets and systems display messages to give feedback about system status and to signal if there are problems with the system.

In this section you should list all those messages, including the audio ones, explain what they mean, and follow them up explaining what to do about it – that is, also provide a troubleshooting section.

For example, let’s say you have four LED lights in the front of your product, or four circles displayed on the status bar of your software. Explain what it means when all lights are GREEN, three GREEN one YELLOW, all YELLOW, all GREEN one RED, etc. Describe what such color combinations mean and then also explain how to take care of the error or malfunction (if it is such) in the troubleshooting section.

Overlap Between Different Types of Guides

As you can easily tell, some of the above information can be included in a User or System Administration Guide as well. The decision what information should go where is a management (or client) decision although, if you are the writer, you can argue your case as well. However it is much better to repeat crucial information in more places than one since you usually have no control over the way technical manuals are used.

For example, you can ASSUME that a customer would refer to the Installation Guide to understand the meaning of System Error Codes but perhaps he or she won’t. Perhaps your customers will only read the User Manual and if the troubleshooting information is included only in the System Admin or Installation guide, they’ll pick up the phone and call your service center to solve a simple problem instead of referring to the Installation Guide.

So, when in doubt, include important information in more guides than one despite the risk of redundancy and repetition.