Quick Start Guides

This document provides a simple template which can be used as a starting point for technical documents intended to get the audience started with a project, tool, or quick setup.

Who should use this template?

Unlike the Walkthroughs, how to's and tutorials template, this is for more advanced users who have some experience with the topic and are looking for a guide they could go through to get started quickly. You should only use this template for your documentation if:

You're expecting an audience with at least some experience with the tool or software being written about.
You do not intend to give a detailed explanation of core concepts; you just want to get the audience started with setting up a tool or software.
You want to have a single document referencing several other documents that explains how to quickly get started with different parts of a software.
You intend to create short onboarding tasks that the user could work on to validate what was learned.
Some tutorials require domain-specific software that needs to be installed as a prerequisite, but some of these installations might not quite fit into such tutorials due to the size. Such installation guides should be created as a quick start guide and fit perfectly into the scope of this genre.

Template

Below is the provided template for this particular genre and is to be duly followed when creating documentation.

Getting started with X

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

This part should provide adequate information about what this document 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 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...

Prerequisite

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?

ExampleThis 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.

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.

This section should be short and concise, like every other section. This is a quick start guide, and your audience only needs minimal information sufficient to get them started. Therefore, sections guiding them through steps in setting up a tool or software should not be bulky or contain unnecessary explanations.

How to do B (Step 2)

This section should follow the same pattern above, like every other section in this guide.

Add more steps...

Onboarding tasks

The previous sections explain how to quickly get started with the software, but most often, after following the steps to set up the software, the audience would want to try out and explore several other parts and ways in which the software can be used. For this purpose, onboarding tasks should be used.

What are onboarding tasks?

Onboarding tasks (in this context) are short, descriptive, actionable documents that provide specific assignments in the form of tasks. The sole aim of these tasks is to get people familiar with the workflow of specific aspects of a particular software, tool, or program by letting them try it out themselves.

These tasks are particularly useful for new contributors to a software. They guide them through what needs to be learned by "learning and doing", which in turn gets them up to speed faster with that software.

An onboarding task should have the following features:

Must be short and descriptive
Should focus on just one small aspect of a software
Should be simple enough to be completed within 30 minutes to 1 hour
Must provide links to helpful resources
Must provide short code snippets or examples that explain what to do

Here are few examples of good onboarding tasks.

More detailed resources

After going through this guide, some users might need more detailed information about the subject. Here is a good place to share links to those.

You should share short notes on what each link teaches, followed by the link itself.

Code samples

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 );

Stewardship

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

Documentation/Quick Start Guides Documentation Template

Contents