Documentation/How-to template

A how-to guide helps an already-competent user reach a real-world goal, such as performing a technical task correctly or working through a problem.

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

Software x user guide (template)

Place the title of the document at the top of the page. Avoid long or vague titles: the title should be sufficient to give enough context about the content of the document. You can read more about choosing the right title in the Style guide.

What is software X?

In your introductory section, cover the following topics if they have not already been covered in a separate overview doc. If they have been covered in a separate overview doc, link to that doc instead. Or, consider excerpts or partial transclusion to reuse introductory sentences from a separate overview doc.

What does the software / tool do?
Why would the reader want to use it?
What does the rest of the doc cover? What will the reader be able to do after reading this documentation?

Examples:

This guide covers how to install and run X, ...

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

Install/setup/configure software X

Prerequisites

State any knowledge your reader should already have before proceeding, or any technical requirements they must complete. Link to resources where the reader can learn or get what they need to meet the prerequisites.

Knowledge requirements
- You should already understand the basics of how to...
- You should be familiar with...
- Which specific tools does your audience have to be familiar with before proceeding?
Software requirements
- Which operating system and what version is required to run the software/tool?
- What additional software must be installed?
- Where can they learn how to install each of the above?
Hardware requirements
- Are there any hardware requirements?
- What's the minimum RAM required for this setup?
Access requirements
- Are certain accounts or permissions necessary to proceed? Which ones, and where does one get them?

Examples:

Running this tool requires at least Node Erbium 12.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 to learn how to install Node JS on Linux.

The examples in this guide run on a Docker container, you need to have MediaWiki Docker set up locally. Follow the instructions to set it up.

Do a thing

This is where you write the instructions for how to complete key tasks to do "the thing". Review the Documentation/Style guide for tips about how to write your text and how to structure your content.

Step 1

Step 2

When your reader completes all the steps, they should have successfully done "the thing".

Do a different thing

Step-by-step instructions for how to do another thing can go here. Note that the heading structure of the doc makes it easier for your reader to skim all the contents and jump to the section that tells them how to do the thing they're trying to do.

Add more steps....

Step 1

Step 2

When your reader completes all the steps, they should have successfully done "the thing".

Code samples

Provide specific code samples within each step that show how to do it. If possible, try to provide code snippets in multiple languages. The Template:Codesample is a good template to have a look at.

JavaScript_Example.js

/*
    hello.js

    MediaWiki API Demos
    Demo of `...` module

    MIT License
*/

var url = "https://en.wikipedia.org/w/api.php"; 

var params = {
    action: "query",
    format: "json"
};

url = url + "?origin=*";
Object.keys(params).forEach(function(key){url += "&" + key + "=" + params[key];});

fetch(url)
    .then(function(response){return response.json();})
    .then(function(response) {
        console.log(response);
    })
    .catch(function(error){console.log(error);});

PHP_Example.php

<?php
/*
    hello.php

    MediaWiki API Demos
    Demo of `...` module

    MIT License
*/

$endPoint = "https://en.wikipedia.org/w/api.php";
$params = [
    "action" => "query",
    "format" => "json"
];

$url = $endPoint . "?" . http_build_query( $params );

$ch = curl_init( $url );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
$output = curl_exec( $ch );
curl_close( $ch );

$result = json_decode( $output, true );

echo( $result );

Next steps

If there are common tasks that are likely to come next, like Troubleshooting, link to those resources.

Get help

How can a reader get support if they get stuck during this process, or if the content in the doc doesn't work? Provide information about:

Who maintains this page
Who to contact for help, and how or where to do that

Real-world examples

Examples of this type of document that may help inspire you: