Last week, we went to IKEA to get some new equipment for our home office.
As you probably know, their instructions are in leaflets with foolproof diagrams to walk you through the assembly process. IKEA are experts at this. instead of long, detailed text-driven instructions they show you how to assemble the items. This works for IKEA as most of their products contain a few pieces which can be slotted together like LEGO.
But what if you’re developing a product that’s more complex than this?
In this case, you need to include additional details, such as pre-requisites, procedures for different operating systems, and screenshots that add value and help the installer, not just eye candy.
In this Klariti tutorial, we look at how to write an installation guide that makes the assembly experience as smooth as possible, and include a series of checklists you can follow to ensure you’ve covered all points. Let’s start.
In this tutorial, we look at how to write an Installation Guide. We look at the main sections in an Installation Guide, how to write each section, and provide sample text to help you get started with your technical documents.
Download: Learn how to write an installation guide template.
The Installation Plan provides installation and configuration procedures for every part of the system and describes the correct order for installing the component instances and performing basic configuration.
An Installation Guide is a type of technical document that describes the steps required to install software, hardware, or any items that requires to be assembled, In this tutorial, we describe how to install a software product, such as a new Windows server, SAP products, or online web applications.
In general, an installation guide is written by a technical writer. Typically, they will work with system administrators and others involved in the installation process for technical information. For example, QA and BAs may also have input.
You can use this Installation Guide template when installing software and for the preparation, training, and conversion from existing systems.
The following Installation and Configuration Guide template provides instructions for installing components on computers that are intended to support and run your product.
The web-based system allows lawyers to create, receive, route, review, and approve legal document online.
Download: Click here to learn more about this installation guide template.
The following prerequisites and requirements must be satisfied in order for the to install successfully.
The installer program runs checks for the software prerequisites, and if any prerequisites are missing, it lists the missing items and requests that they be installed. The installation will not proceed until all prerequisites are installed.
Identify the server prerequisites, such as:
Identify IIS requirements, such as:
Identify hardware requirements, such as:
Computers running must meet the following hardware requirements.
Identify software prerequisites, such as:
The installation setup program runs checks for the following software prerequisites:
Identify other installation requirements, such as:
The following installation requirements must also be completed:
Describe the web server configuration, for example:
Identify the component installation files.
| Component | Installer File |
| Identity component #1 | Identify the installer file, e.g. .exe, msi. |
| Identity component #2 | Identify the installer file, e.g. .exe, msi. |
| Identity component #3 | Identify the installer file, e.g. .exe, msi. |
Download: Click here to learn more about this installation guide template.
Use the following checklist to ensure that your servers are ready for the components to be installed.
| # | Checklist Item |
| 1 | Copy [file] to the [directory]. |
In the next section, describe the steps to install and configure the components.
To make this easier to follow, list the tasks and the steps the System Admin needed to follow:
The installation procedure contains the following steps:
| # | Checklist Item |
| 1 | Configuration pre-requisites |
| 2 | Ensure that servers meet minimum hardware requirements. |
| 3 | Ensure that software prerequisites are installed. |
| 4 | Run the installer program on the server. |
| 5 | Run the DB installer program on the server. |
| 6 | Install the database. |
| 7 | Import data |
| 8 | Configure API endpoints |
| 9 | Install Application Server |
| 10 | Install APIs |
Download: Click here to learn more about this installation guide template.
In this section, we describe the post installation tasks.
After you’ve completed the installation, you want to check that everything works fine.
To ensure this, let’s create a checklist and check that everything works correctly.
Use the following checklist for post-installation and configuration requirements.
| # | Checklist Item |
| 1 | Check the API endpoints are correct. |
| 2 | Check that the database tables are running. |
| 3 | Check that digital certificates are installed. |
| 4 | Check that you can access the web servers. |
| 5 | Check that security settings have been applied correctly. |
In this section, we help users fix common issues that may arise.
To do this, identify known issues, common mistakes users may make when configuring the system, and any recommended settings.
The following installation issues may occur when installing .
Internal Error 123.
Download: Click here to learn more about this installation guide template.
The next step is to validate that the installation was successful.
Use the following checklist to validate that was installed successfully.
Use the following validation checklist, or portions of it, to validate a successful installation of the components.
| # | Checklist Item |
| 1 | The URL should point to [endpoint]. |
The URL should follow the format:
Finally, explain how to uninstall the product. You might also want to include steps to upgrade the application.
You can uninstall previous versions of using the Add/Remove Programs feature on the Control Panel.
Uninstall the components in the following order:
Download: Click here to learn more about this installation guide template.
As we’ve seen, to reduce friction during the installation experience, test the installation steps as if you were the person installing the software.
This means that if you want to increase customer loyalty to your product make sure that the installation experience is so smooth that others will recommend it to the friends. IKEA has set the benchmark for simple-to-follow installation instructions. Can you take inspiration and apply these principles to your software?
