Writing a Getting Started Tutorial

Photo by David Iskander on Unsplash

A mark of any popular product or technology which enables its adoption is good documentation. An in-depth documentation gives all users the freedom to explore the immense features of your application. On the other hand, a long singular technical document would deter the impatient and turn away potential adopters.

A simple way to avoid such a situation is to have a “Getting Started” section at the head of your documentation. It should contain a simple set of instructions to quickly get your service up and running, either to quickly sample, or if possible, a minimum viable ready-to-use product.

In this article, I suggest an outline for such an article.

It is a great idea to divide the document into sections as such:

1. Introduction
2. Prerequisites
3. Steps

Introduction

This section includes a short paragraph about the document. Some points to include are support for operating systems, browser support if it’s a web app. A list of popular technologies used can also be added.

Example

Introduction for Composer, a PHP Dependency Manager

Prerequisites

A list of all softwares needed to be installed before your application can be installed. You can either provide an installation instruction yourself, but it would be a better idea to link to their respective installation/download pages.

Also mention the specific version of your requirement if it is critical to the working of your application. You wouldn’t want users to fail just because a backwards incompatible change was introduced in your requirement.

Example

If your application is built on NodeJS, simply mention that NodeJS is required and add a link to the installation documentation.

A good example of this would be Cronicle. Notice how it mentions and links NodeJS installation.

If you are shipping a docker image for easy installation, you should also add Docker in this section and link to the Docker Installation.

Steps

Cleary breakdown the procedure into logically independent steps. I have seen a few documents comprising solely of a single long code block with just shell commands. Most of the times, the user will copy-paste the whole thing, generally resulting in an error because they missed to replace a custom variable.

Such long scripts can be easily broken down into various steps so that the user spends time understanding each step, thus drastically reducing above errors.

Although, it would be overkill to use a step for every single command.

Example

This tutorial on How To Install Node.js by DigitalOcean clearly chalks out my point. Notice how each command has been given dedicated space as to ensure a user’s attention to the important bits.

A good example with explanation for each command

Below is a bad example which might end up confusing users if all the commands are directly pasted in the terminal as it contains a nano command as well as an apt install which may ask for permission.

A bad example to Install NodeJS

Tips

1. Write all code in code blocks. (Syntax highlighting could be a nice add-on)
2. $ before all shell commands.
3. Use screenshots.
4. Link to external resources if you reference them in your documentation.