Software products need a good installation guide. It lists all necessary precondition and steps to finally use the software application.
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.
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.
The following sections describe the main elements of a software installation guide template. It can be used as a software installation manual template.
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.
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
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.
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.
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.
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.
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, …).
Typical problems that might occur during the installation should be listed here. Check that the correct version and latest release is mentioned.
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 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:
URL of the installation guide for Slack Windows client: https://slack.com/help/articles/209038037-Download-Slack-for-Windows
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):
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.
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.
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.