Tutorial

4 min read

A tutorial is a comprehensive and detailed guide that teaches users how to perform a series of tasks or understand concepts in depth.

In this guide, you’ll see the available template, general guidelines, and examples of tutorials.

Make sure to review the guidelines from the Best practices for writing documentation.

Differences between a tutorial and a how-to guide

While both tutorial and how-to guide are instructional resources, they have some differences in their structure and purpose:

Purpose

Tutorial	How-to guide
Learning-oriented. Teaches a broader concept, skill, or process in detail.	Task-oriented. Focus on helping the user complete a specific task or goal.

Scope

Tutorial	How-to guide
Covers a series of steps or concepts, often related to learning a new skill.	Narrow in scope, typically covering one task or process divided into steps.

Content

Tutorial	How-to guide
Educational, offering context, background, and explanations.	Practical, with direct, task-oriented instructions.

Audience

Tutorial	How-to guide
Users who want to learn a skill or understand a concept deeply.	Users who need to quickly achieve a specific goal, usually with prior knowledge.

Writing a tutorial

Topic	Tutorial
Title	Directly states the tutorial's goal with a verb in the gerund form. Consider your target audience and the specific action you want them to complete. For example: `Managing users in B2B organizations`
Before you begin (optional)	Lists all necessary prerequisites the user must meet or complete before following the steps in the guide, including: Tools and software requirements: Specify the minimum system requirements, such as operating system versions, specific software installations, and hardware configurations. Account creation or setup: If the user needs to create an account or set up specific configurations, it provides clear instructions or links to relevant resources. Basic knowledge or skills: If the guide assumes a certain level of familiarity with specific concepts or tools, it briefly outlines those prerequisites or provides links to additional learning resources.
Steps	The steps will be presented as a list. The list is in the templates after the sentence `Here's an overview of the parts`. Provides detailed, step-by-step instructions for completing the task or achieving the goal. Breaks the process into steps, ensuring each step is clear and actionable. Considers what the user needs to accomplish by the end of the guide and outlines every necessary task to get there. For example, if the goal is to manage an Admin module, consider each step the user needs to complete to achieve that.
Content of the steps	Each step should guide the user from one point to the next in a logical sequence. Where relevant, it includes examples, media, or warnings to help users. Each line of the instructions must correspond to a step to be taken by the user. Don’t assume user knowledge. For example, if the user must press `Enter` in a step, include that instruction as part of the step. Use angle brackets (`>`) to break down complex steps or combine simple ones for sequential actions. For example: 1. In the VTEX Admin, go to Storefront > Site Editor. Maintain consistent verb tense throughout the instructions by using imperative verbs. For example: 1. Click File > New > Document..

Tutorial templates

Template 1

# [Tutorial title]

[Provide a short description of the tutorial, including the skills or knowledge the user will acquire by the end of it.]

Here's an overview of the parts:

<Flex>

<WhatsNextCard
title="Step 1. title"
description="Provide a short description of the step."
linkTo="https://developers.vtex.com/docs/guides"
linkTitle="See more"
/>

<WhatsNextCard
title="Step 2. title"
description="Provide a short description of the step."
linkTo="https://developers.vtex.com/docs/guides"
linkTitle="See more"
/>

<WhatsNextCard
title="Step 3. title"
description="Provide a short description of the step."
linkTo="https://developers.vtex.com/docs/guides"
linkTitle="See more"
/>

...

## Before you begin

[Lists all prerequisites the user must meet or complete before following the steps in the guide.]
 
</Flex>

Template 2

# [Tutorial title]

[Provide a short description of the tutorial, including the skills or knowledge the user will acquire by the end of it.]

Here's an overview of the parts:

- [Step 1. Title](https://developers.vtex.com/docs/add-the-step-slug-here)
- [Step 2. Title](https://developers.vtex.com/docs/add-the-step-slug-here)
- [Step 3.](https://developers.vtex.com/docs/add-the-step-slug-here)
...

## Before you begin

[Lists all necessary prerequisites the user must have or complete before following the steps in the guide.]
 
</Flex>

Differences between a tutorial and a how-to guide

Writing a tutorial

Tutorial templates

Tutorial examples