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 = Below is the provided template for this particular genre and is to be duly followed when creating documentation.

= 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 requires 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 should 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 with 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 at least Node Erbium(v12.x.x) and npm version 6.12.0. You're expected to run at least 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 instructions here to set it up.

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

Depending on the steps required to install and set up 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 involves a lot of steps and might be a bit tedious to go through. If the setup and installation are 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 syntaxes that are hard to understand, the code should be readable, self-explanatory, and clean. Additionally, If possible, try to provide code snippets in multiple languages. The API:Documentation template/Sample code1 is a good extension to have a look at.

Conclusion
By now, you're done explaining the tutorial. The conclusion should include a summary of what was learned and how to further use that knowledge.

If there are links to other useful resources the audience would find helpful, here is a good place to share them.

Stewardship
Here, you would share useful information about the following;


 * Who maintains this page.
 * The project is written on.
 * How to contact the author and maintainers of this project(only share public information here, e.g zulip or IRC).
 * Links to discussion pages/threads.