Tutorials

Tutorials are essential for helping new users feel confident that they can successfully use your tool. A good tutorial demonstrates how to use the tool by guiding users through hands-on examples. Because users may have different operating systems and varying levels of experience, it’s especially important that tutorials always work as intended. Encountering errors while following a tutorial can be discouraging and may cause users to give up or seek alternative tools.

Throughout this section of the guide, we’ll refer to two types of tutorials: the Basic Use Case tutorial and Additional tutorials. Every project should include at least one Basic Use Case tutorial that new users can complete immediately after installation and before engaging with any other part of the documentation. This tutorial serves as their first successful interaction with your tool.

Additional tutorials expand on the Basic Use Case by introducing other features or workflows. They’re especially helpful for beginner users who want to explore more capabilities, but they aren’t strictly required for your documentation to feel complete.

Tutorials differ from How-To Guides or Examples in their intended audience and purpose. Tutorials are written for new users who are getting started, either with your tool as a whole or with specific features of it. In contrast, How-To Guides and Examples are meant for more experienced users who already understand the basics and are looking to accomplish a specific task. These resources often include less explanation of what each step is doing because their audience already has context.

Highlights of this section:

• What makes a tutorial good or bad
• How understanding your intended audience shapes content and tone
• How to ensure your tutorial is accessible to users with vision impairments

Remember that tutorial Markdown templates are available in the companion repository!