Documentation/How-to template

= Walkthroughs, how to's and tutorials =

This document provides a simple template that can be used as a starting point for technical documentation that are intended to walk readers through the steps of using and setting up a particular tool or software.

Who should use this template?
This template isn't suitable for all forms of documentation, you should only use this document as a guide/starting point for your documentation if;


 * You want to provide a detailed step to step explanation of a software or tool.
 * Your documentation is for people of all skill levels(beginners inclusive).
 * You intend to provide sufficient code samples, diagrams, and workflows where necessary.

= Template = The below is the provided template for this particular genre and is to be duly followed when creating documentations.

= How To Install/Setup/Configure Software X = The title of the documentation should be written boldly at the top, and should not be too long or vague. The title should be naturally sufficient to give enough context to what the article is about. You can read more about choosing the right title in the Article titles, headings, and sections here.

Introduction
This part should provide adequate information about what this documentation is about, what will the reader learn?

What approach did you take in explaining this concept?

What will the reader be able to do after reading this documentation?

In this tutorial, we would be setting up X and I would walk you completely through the setup....

By the end of this tutorial, you would be able to do X in Y ways using Z...

Prerequisites
Some documentation require domain specific knowledge which would not be discussed in the tutorial, such prerequisite knowledge should be explicitly stated with links pointing to useful resources where this prerequisite knowledge could be acquired. More explicitly, you shoud look out for and/or add the following to prerequisites of your documentation.


 * Software requirements
 * Which operating system and what version is required for this tutorial?
 * Which additional software installation is needed?
 * Which specific tools do your audience have to be familiar before proceeding?
 * Where do they learn how to install each of the above?
 * Hardware requirements
 * Are there any hardware requirements?
 * What's the minimum RAM requirements in which this setup can run on?

Example

This tutorial requires atleast Node Erbium(v12.x.x) and npm version 6.12.0. You're expected to run atleast Ubuntu 18.04 with a minimum of 8gb RAM.

Follow the instructions here to learn how to install Node JS on Linux.

The examples in this tutorial run on a docker container, you need to have mediawiki docker setup locally. Follow the instructons here to set it up.

Installation and Setup Guide (Optional)
Asides software installation prerequisites, there might be some domain specific softwares that might be great to walk your audience through its installation and setup.

Depending on the steps required to install and setup a specific software, you might want to consider moving this to an entirely new document as a Quick Start Guide(Link to be added when genre template is created) if it's involves a lot of steps and might be a bit tedious to go through. If the setup and installation is quite basic and won't take a lot of time, it should be done here. Note that whichever of the above you choose to go with, the provided guide should be sufficiently detailed enough to keep your audience going with no external help.

How to do A (Step 1)
This is where you begin to write the actual documentation, before proceeding, take some time to review the Documentation/Style guide again.

This section shouldn't be too technical, it should majorly be introducing the audience to the first few steps of the tutorial, additionally, you should state what was achieved in the step at the end, and what the next step would be walking the audience through.

How to do B (Step 2)
In this step, you can choose to dive into the technical aspects of the tutorial. This step and the ones after should be written with beginners in mind.

Add more steps....

Code Samples
The code samples provided in your tutorial should be intuitive enough and not contain too many syntax that are hard to understand, the code should be readable, self explanatory and clean. Additionally, If possible, try to provide code snippers in multiple languages. The API:Documentation template/Sample code1 is a good extention to have a look at.

Code Samples - API:Documentation template