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
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
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.
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
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.
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.
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.
Step 4 – Adding More Steps
Add as many more steps as you need to guide your reader through the process.
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