This repository has been archived by the owner on Sep 24, 2022. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 171
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
76b8345
commit 5bd4081
Showing
1 changed file
with
43 additions
and
10 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,21 +1,54 @@ | ||
# Tutorial templates | ||
# The tutorial template | ||
|
||
The tutorial templates include placeholder text that you can replace with your own text. This text is indicated in {curly brackets}. | ||
The tutorial template includes placeholder text that you can replace with your own text. This text is indicated in {curly braces}. | ||
|
||
## Why do I need tutorials? | ||
|
||
Tutorials are integral to helping your users become acquainted with your product. They are learning-oriented, which means that they teach users how to do something, like learning how to debug a JavaScript application. | ||
Tutorials are integral to helping your users become acquainted with your product. They are learning-oriented, which means that they teach users how to do something, like learning how to debug a JavaScript application. | ||
|
||
Tutorials are often confused with how-to guides because they do help users achieve a specific end. However, how-to guides assume that your users have some experience with your product or are familiar with the basics. | ||
Tutorials are often confused with how-to guides because they do help users achieve a specific end. However, how-to guides assume that your users have some experience with your product or are familiar with certain concepts. | ||
|
||
In comparison, tutorials help beginners understand the concepts they need to use your product and understand the rest of the your documentation. | ||
In comparison, tutorials help beginners understand the concepts they need to use your product and understand the rest of your documentation. | ||
|
||
## Overview of the tutorial templates | ||
## About the tutorial template | ||
|
||
There are three types of tutorial templates included in this directory: a quickstart tutorial template, a modular tutorial template, and a deep dive tutorial template. | ||
This tutorial can be used in one of two ways: for providing a walkthrough of a particular feature, or walking users through completing a small project. Ideally, your users already completed a quickstart or "getting started" tutorial and have a general understanding of your product. | ||
|
||
The [quickstart tutorial template](quickstart-tutorial/about-quickstart-tutorial.md) is installation-focused and guides your user through installing your product and completing a small project to verify installation. | ||
### About the "Overview" section | ||
|
||
The [modular tutorial](modular-tutorial/about-modular-tutorial.md) template provides a walkthrough of a particular feature. It's for users who have completed the quickstart tutorial. | ||
Use this section to provide an overview of what learning objectives or goals users will complete in this tutorial. You can also explicitly state who this tutorial is for and what required background knowledge is needed. | ||
|
||
The [deep dive tutorial](deep-dive-tutorial/about-deep-dive-tutorial.md) template provides users the opportunity to learn more about a particular feature. It builds upon the knowledge learned in the modular tutorial. This tutorial can present learners with a hypothetical scenario or provide a starter project to help guide their learning. | ||
### About the "Background" section | ||
|
||
The purpose of the background section is to provide any necessary context for your users before they start your tutorial. | ||
|
||
If you're writing a tutorial that's focused on learning how a particular feature works, you might describe that feature here. For example, a tutorial around using Microsoft Visio's templates to build flowcharts might start with an explanation of how flowcharts are used or what flowchart shapes represent. | ||
|
||
If you're writing a tutorial where you provide users with a starter project, you could describe the project hierarchy here. For example, a tutorial around building a website with HTML, CSS, and JavaScript might explain how the folders are organized, what code is provided for the user, or what they need to add. | ||
|
||
### About the "Before you begin" section | ||
|
||
Use this section to list any prerequisites for completing the tutorial. This may include operating systems, languages, package managers, or software. | ||
|
||
### About the "Steps" section | ||
|
||
The steps section is where you describe what the user needs to do. How you write your steps will vary depending on your organization's style guide. | ||
|
||
This template breaks down the tutorial into _parts_. One _part_ of the tutorial may focus on completing several related steps. You're welcome to follow this structure or use the step headings on their own. | ||
|
||
#### Tips for writing steps in a tutorial | ||
|
||
* When writing your steps, make sure to provide any background information your users may need to complete the task. | ||
* Remember to orient your users when walking them through each step. If they need to open a particular file or dialog to complete the task, provide that information first. | ||
|
||
### About the "Conclusion" section | ||
|
||
Use the conclusion section of the tutorial to sum up what tasks your user completed during the tutorial and what your users now know how to do. | ||
|
||
### About the "Next Steps" section | ||
|
||
Use this section to include links to other tutorials, such as tutorials that allow users to learn about other features. You can also include links to relevant resources, like articles, blogs, or videos. | ||
|
||
## Helpful tips when writing your tutorial | ||
|
||
* Keep your tutorial focused. If needed, link out to other pieces of documentation that might explain some concept in more depth. |