Documentation/Quick Start Guides Documentation Template

= Quick Start Guides = This document provides a simple template which can be used as a starting point for technical documentation 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 experienced/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/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/software.
 * You want to have a single document referencing several other documents that explain how to quickly get started with different parts of a software.
 * You intend to create onboarding short tasks that the audience could work on to validate what was learned here.
 * Some tutorials require domain-specific software that needs to be installed as a prerequisite, 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 documentation 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 to what the article is about. You can read more about choosing the right title here - Article titles, headings, and sections here.

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 would be setting up X and I would walk you through the setup....

By the end of this tutorial, you would have gotten more familiar with X...

Prerequisite
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 the 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 does 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 guide 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 guide run on a docker container, you need to have MediaWiki docker setup locally. Follow the instructions here 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 again.

This section should be short and concise as well as 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, as well as every other section in this guide.

Add more steps...

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

What are onboarding tasks?
Onboarding tasks(in this context), are short descriptive, and 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 particularly come in handy for new contributors to a software, it guides 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 little aspect of a software.
 * Should be simple enough to be completed in 30mins - 1 hour.
 * Must provide links to helpful resources
 * Must provide short code snippets or examples that explain what the audience is to do.

Here are few examples of good onboarding tasks.

- https://phabricator.wikimedia.org/T248220

- https://phabricator.wikimedia.org/T249323

- https://phabricator.wikimedia.org/T248232

More detailed resources
After going through this guide, some audience 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 enough 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 API:Documentation template/Sample code1 is a good extension to have a look at.

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


 * Who maintains this page.
 * The project this page is written about.
 * 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.