In this tutorial you can learn how to make a tutorial.

A tutorial is a lesson that takes you by the hand through a series of practical steps. It offers a learning experience by doing something. It is the best way to get to know a subject you are not yet familiar with.

 Tutorials are crucial in any documentation: they show newcomers around, they guide the first steps, they are the shopping window, they give a nice and easy experience of a topic. One of the "tricks" to obtain this is to leave out everything that can distract in the learning process. For instance:

• Alternative ways to do something or ways to do something very specific.
• Complete references of all options and a technical description of its structure.
• Detailed explanations and historical backgrounds.

That extra information can best be provided separately. Avoid as much as possible to mix it in, as it will only cloud the tutorial. This is the main principle of the Diátaxis Framework, a systematic way to improve documentation. Put the above mentioned extra information into respectively how-to guides, references and explanations. In the how-to guides you can quickly find how to get something specific done. In  references you can look up how things work, what options they have and where to find more information. With explanations you can deepen your understanding of the topic.

Although a tutorial offers an introduction to a topic, it is not exclusively aimed at beginners. It can also be an introduction to an advanced topic! Be clear at the beginning of your tutorial about what knowledge or skill is needed to be able to do the tutorial.

If you teach someone how to cook, you have to explain things like cutting techniques, how to use an oven and other basic kitchen stuff. You start with some simple recipe, preferably something that easily gives a nice end product. That end product itself is not the main goal: you want to teach some skills. This is what a tutorial does. Someone who knows how to cook and wants to make something specific, doesn't need such a tutorial, but a recipe. Recipes are the how-to guides of cooking.

Step-by-step

To create a tutorial:

1. Gather information about the topic. Existing documentation, videos, etc. Note things you find confusing or took you some time to understand. Are there any questions about the subject on the forum?
2. Which concepts are involved? Doodling a small diagram can help. Don't try to be complete, but make clear what is important for this tutorial and what not.
3. Is there any specific knowledge or skill necessary to teach in your tutorial?
4. Create an example in which you can use all concepts and skills you want to convey in this tutorial. Make the example as simple as possible.
5. Define and write steps to come to an end result. Each step should be reproducable by your student.
6. Filter out all eplanations, references, alternatives and special cases: put them in separate articles.
7. Write an introduction. What will you learn in this tutorial? Mention any prerequisites necessary to do the tutorial.
8. Write the summary. What did we learn? You can also mention what next steps to take to learn more.
9. Add screenshots with annotations to illustrate the actions to take. Tip: use numbers in the screenshot and give explanations in the text. That makes it easier to reuse your screenshot in translations and minimises the effort to produce language-specific screenshots.
10. Add diagrams to explain structures, relations and processes.
11. Add the accompanying articles with explanations, references and how-to guides.
12. Put all articles of one subject under an overview article, explaining what is what, how they relate and where to start.

Example: Create and publish an article in Joomla

As an example, let's create a tutorial how to create and publish an article under a menu-item in Joomla.

Information gathering

In our user manual you'll find relevant articles under "Getting started", "Articles" and "Menus". It is often confusing when starting with Joomla, that you don't see an article after you have created one, even though you have marked it as "published". In order to see the article, there has to be a link to it. There are several ways to create such a link (like a menu-item or a category blog layout or by putting it on the home page blog layout by marking the article as featured or linking from another article), but we will now focus on making the article available via a menu-item.

Concepts & Skills

We have 'content', 'article', 'menu' and 'menu-item'. We have to clarify those terms. We show where to find those things in the admin menu. We leave out 'categories' or 'featured' in this tutorial.

Prerequisites

You have to have access to the administrator side of a working Joomla website and know how to login.

Goal

Our goal is to learn how to create a new Joomla article and a new menu-item under which we put our article.

Steps

Use the following steps to accomplish our goal:

A. create an article

1. Log in to your Joomla administrator panel.
2. First we will create the article. Navigate to the "Content" menu on the left and select "Articles".
3. Click "New" to create a new article.
4. Enter a title and content for your article.
5. Click "Save & Close" to save your article.
   
   

B. Create a menu-item linking to the article

in order to show the article on the website we will create a menu-item linking to the article. Navigate to the "Menus" menu on the left and select "Main Menu".

1. Just like with an article, click "New" to create a new menu-item.
2. Enter a title for your menu-item. This is the title as it will appear in the menu. It doesn't have to be the same as the title of the article. It usually is shorter than the title of an article in order to better fit into the menu.
3. Select a menu-item type: under "Articles" select "Single Article".
4. Select the article: select the article we just made.
5. Go to the website and refresh. Congratulations: you are now able to click on the menu item to see your article.

Introduction

Write the introduction: what will you learn in this tutorial and what prerequisites are necessary.

Filter out additional information

Can we leave out anything in what was written until now? Well, in step 2 of creating a menu-item I mentioned the title of the menu-item doesn't have to be the same as the title of the article. Is that a necessary addition to this tutorial? If not, then we better leave it out for now. But it gives a hint for a more specialised article about article titles and menu titles and when they are displayed, involving the general article options, the individual article settings under the options-tab, the menu-item settings under the options-tab of the menu-item and more. It would also be good to make a reference-type article about how articles, categories and menu-items work together; in such an article try to be complete, list all possibilities. A specialised how-to article could be: "How to display the article title?", showing the settings in the general article settings, and in the individual article and menu-menu settings. An explanations-type article could tell something about the background why Joomla uses "article" where for instance WordPress uses "post" or how the article is rendered in the final page.

Conclusion

Wrap up everything in a summary. And mention some possibly next steps to learn more (like: a tutorial about adding a category or a how-to guide about the save-to-menu shortcut).

Images and graphics

Make screenshots showing the buttons and fields involved in creating an article and a menu-item. Mark the buttons and fields involved.

For clarity you could add a diagram showing how an article is put "under" a menu-item.

Add references, how-to guides and explanations

Put all additional information and instructions in separate articles.

Overview

If you have multiple articles about one topic, you should make an overview article, explaining how the articles relate and where to start.

Excercise

Start making the above tutorial how to create and publish an article in Joomla. The best way to learn is by doing. We will publish an example how this can look like in the current user manual (sandbox) site. But we would be happy to put your version there if you can improve the current one.