Tutorial Template

This template can be used for creating tutorials, whether they are in the handbooks or elsewhere. This should give you a format to follow and make it easier for you to get started writing your tutorial. You can use this template as a framework, replacing the text with your own.

Overview Overview

The overview should introduce the reader to what they will do in the tutorial. You should provide an ordered list of what the reader will learn. When you have finished reading this tutorial, you will be familiar with:

  • creating awesome tutorials
  • tutorial formatting and layout
  • how to write a tutorial
  • how to use this template to create your tutorial

Top ↑

What You Will Need What You Will Need

Use this section to tell the reader what they will need, or any prerequisite knowledge they will require to complete the tutorial. For example:

  • a local WordPress installation or test site
  • a plugin like Theme Check
  • to have read the page on Permalinks in the Codex

Replace these items with items specific to your tutorial.

Top ↑

The Tutorial The Tutorial

The handbook plugin on WordPress.org will generate a in-page ToC at the top of the page. This will create a useful overview of the tutorial that the user can refer back to.

Step 1 – The First Step Step 1 – The First Step

Break your tutorial down into discrete steps that the reader can follow. A task should be broken down into as many steps as are needed.

Top ↑

Step 2 – The Next Step Step 2 – The Next Step

Step two should follow logically from the first step. This may seem intuitive but there are many tutorials out there that double back on themselves. A good approach to take is to work through the task, noting the steps in order as you do so.

Top ↑

Step 3 – Adding Some Color Step 3 – Adding Some Color

Use callouts and images liberally.

On WordPress.org we use the Syntax Highlighter Evolved plugin. Wrap your code in the correct [language] shortcode. Commonly-used shortcode languages include php, html, css, js, sql, shell, and bash (see this reference for all available languages).

Tip: Follow the language and style used here. Use as few words as possible, and always write in the second person.

Top ↑

Step 4 – Adding More Steps Step 4 – Adding More Steps

Add as many more steps as you need to guide your reader through the process.

Top ↑

Learn More Learn More

Now that the reader has completed your tutorial, they’ll want to learn more. Add a list of resources for further reading:

  • Awesome resource 1
  • Another awesome resource
  • A pretty good resource
  • A useful resource