The Installation Guide is a specific documentation for the IT or operations department. It describes how a specific product or software application needs to be installed. Also prerequisite, system requirements, configuration options and maintenance can be included. It can be part of the operating manual or be a separate document.

How to write an installation guide?

The installation guide is created by a technical writer or somebody from the support team. A good installation manual template can be used as a baseline and the appropriate sections filled with the specific steps how to install the software or product.

The installation of a on premise software that is installed on a desktop computer, or a server via command line or setup application to a device – is different than the installation of a iOS or Android App, that can be downloaded and installed from the Apple AppStore or Google PlayStore.

For web-based applications that are consumed as Software-as-a-Service or Cloud Application, the installation is not physically but only configuration of the company account and onboarding of the users. Additional, the integration of the Single-Sign-On (SSO) with the local Active Directory, or a cloud-based AD as Microsoft Azure is necessary for a good integration.

Installation guide template

The following sections describe the main elements of a software installation guide template. It can be used as a software installation manual template.

Installation guide template

Introduction

Describe the product in 1-2 paragraphs and the purpose of this document. Mention the current software version and release, this installation document is based on.

Pre-installation Requirements

List all prerequisites and dependencies that are necessary to install the software correctly. This includes specific hardware (e.g. for a server, the number and type of CPU, RAM, Hard Disk type (e.g SSD), file system / partition and required disk space).

Also the necessary software should be defined with the required (minimal) version and release. This could include the following elements

Operating System: Linux as e.g. a specific Linux Distribution (red hat enterprise linux, debian, ubuntu) or Windows (Windows Server, Windows 11, …)
Database: if required, e.g. MYSQL, PostgreSQL, Microsoft SQL Server (edition and version)
Web Server: if required, e.g. Microsoft Internet Information Services (IIS), Apache, nginx
Application Server: if required by your software, specify the vendor, name and version of the application server (if not automatically installed by your software’s installer)
Libraries and additional software: if any specific software or library is necessary, list it (e.g. .NET environment, JAVA SDK, …)

If possible and useful, create a pre-installation checklist. For the user or administrator that performs the installation, this is very handy and helps to not forget any item and task.

Installation instructions and steps

A step by step list of instructions. They should be as precise and exact as possible. If a package manager is used, write the correct installation command with the correct parameters. If the installation document is a pdf file or consumed online, make sure the commands can be copied easily (no screenshot, only text – maybe use a specific terminal-like font) so the administrator can copy the commands.

If multiple installation method are available, all should be covered (e.g. simple or advanced mode). The installation process should describe also the detailed instructions.

Configuration settings

When the installation is finished, the configuration file and configuration settings might be updated. The default configuration and values might not be good for every customer. So list all necessary configuration files or screens, along with the configuration elements and possible values. It must be clear to the reader what is to be checked and what is the expected outcome and result.

Post-Installation Tasks

When the installation and configuration has been finished successfully, there might be some cleanup-tasks necessary. This could include e.g. removing the installation files, cleanup the temp folder or configure a database backup.

Post-installation checklist

When the complete installation is done, the administrator should verify the installation. If your application provides such a “self-check” describe how to run and evaluate the result. Otherwise describe the main items to be checked (e.g. if a user can login, if the database is updated, if log files are created and contain specific values, …).

Troubleshooting

Typical problems that might occur during the installation should be listed here. Check that the correct version and latest release is mentioned.

Installation guide examples

There are various good and poor examples of installation instructions published. The following samples can be used as a reference. They are written for different, but typical software products that target business to business (b2b) software products.

Slack installation guide

Slack is a messaging app for business (copied by Microsoft Teams). It is a typical client/server application that has a cloud-based backend/server that is configured by the administrator. The clients can be installed to the users physical Desktop computers or virtual desktops, or on their tablets and smartphones.

The installation guide is part of the “Getting started” section that introduces Slack and main concepts, a getting started section for the (new) Slack admin and a getting started section for new users.

So only the installation of the clients for Windows, Mac, Linux and the mobile apps needs to be described in specific installation instructions. It is part of the slack help center and lists the 2-step process:

Step 1: download the slack app from the download page, or from Windows Store
Step 2: sign into the workspace
Optional, additional options are described

URL of the installation guide for Slack Windows client: https://slack.com/help/articles/209038037-Download-Slack-for-Windows

Microsoft SQL Server installation guide

Installing the Microsoft SQL Server is quite complex. It runs on different operating systems on premise and in the cloud. There are multiple versions and licensing options available. The SQL Server has various options and modules that can be installed with the installer.

So this installation guide is a good example for a very complex software product and contains the following elements (only a selection):

Getting started
Installation media
Considerations
SQL Server installation: list of more than 10 different installation articles (!)
Individual component installation
SQL Server configuration

URL: https://docs.microsoft.com/en-us/sql/database-engine/install-windows/install-sql-server

FAQ and typical questions

Who writes the installation guide?

The author of an installation manual is a technical writer. If no documentation team exists, this could also be somebody from the support team or development department.

When to update an installation guide?

The installation guide should be updated and checked after each update and new release. Also, when the defined dependencies as e.g. a new version of the operating system or used libraries are published, the installation guide should be checked and validated, if the commands are still correct or lead to an error.

Need help to create your installation instructions?

If you have a question or need some more information about the process of installation manual creation, reach out to us. Subscribe to our newsletter to get more information and content about multilingual documentation.

This page is part of the comprehensive list of documentation types.
[Continue reading]