Documentation/Walkthoughs, how-tos and tutorials templates

From mediawiki.org
Jump to navigation Jump to search

Walkthroughs, how tos, and tutorials[edit]

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

Who should use this template?[edit]

This template isn't suitable for all forms of documentation. You should only use this template as a guide or starting point for your document if:

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

Template[edit]

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[edit]

The title of the document should be written at the top in bold text and should not be too long or vague. The title should be sufficient to give enough context about the content of the article. You can read more about choosing the right title in the English Wikipedia Manual of Style.

Introduction[edit]

This section provides adequate information about what this document is about:

What will the reader learn?

What approach will you take in explaining this concept?

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

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

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

Prerequisites[edit]

Some documentation requires domain-specific knowledge which is not discussed in the tutorial. Such prerequisite knowledge should be explicitly stated with links pointing to useful resources where this knowledge could be acquired. More explicitly, you should look out for or add the following to the prerequisites of your documentation.

  • Software requirements
    • Which operating system and what version is required for this tutorial?
    • What additional software must be installed?
    • Which specific tools does your audience have to be familiar with before proceeding?
    • 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?

Example

This tutorial 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.

Installation and setup guide (Optional)[edit]

Aside from software installation prerequisites, there might be some domain-specific software that would be great to walk your audience through the 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 if it involves a lot of steps and might be a bit lengthy. If the setup and installation are quite basic and won't take a lot of time, it should be done here. Note that whichever approach you choose to go with, the provided guide should be sufficiently detailed to keep your audience going with no external help.

How to do A (Step 1)[edit]

This is where you begin to write the actual documentation, before proceeding, take some time to review the Documentation/Style guide.

This section shouldn't be too technical; it should introduce the audience to the first steps of the tutorial. Additionally, you should state what was achieved in the step at the end and what the next step would be.

How to do B (Step 2)[edit]

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[edit]

The code samples provided in your tutorial should be intuitive and not contain too many syntaxes that are hard to understand. The code should be readable, self-explanatory, and clean. 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 );


Conclusion[edit]

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 resources the audience would find helpful, here is a good place to share them.

Stewardship[edit]

Here, you would share useful information about the following:

  • Who maintains this page
  • What projects are included
  • How to contact the author and maintainers of this project (only share public information here, like Zulip or IRC)
  • Links to discussion pages or threads

Example[edit]