Tutorials or How-to Guides
Disclaimer: This page contains my personal reading notes on the Diátaxis documentation framework.
What this notes cover &#xNAN;My checklist (draft) to distinguish between tutorials and how-to guides applying the Diátaxis documentation framework.
Overview
To distinguish a tutorial from a How-to guide we need to think about the following document aspects:
Goal orientation
User's prior knowledge
Scope and depth
Format and structure
Result
Level of detail
Examples and practical application
In the following section, you will find a table to help you identify if your document or draft is a tutorial or a checklist.
Tutorial or How-To Guide? A Checklist
For each of the following documentation aspects select the sentence that best describes your document or draft:
Goal Orientation
The primary purpose of the document is to guide the user through a series of steps to achieve a broader understanding or a comprehensive goal.
The primary purpose of the document is to solve a specific, practical problem or to accomplish a specific task?
User's Prior Knowledge
The document is designed for beginners or users with limited prior knowledge of the subject?
The document is meant for users with some understanding or experience who need specific instructions.
Scope and Depth
The document covers a wide scope, providing a general understanding of a topic or tool.
The document focused on a narrow topic, aiming for depth in a specific area.
Format and Structure
The document follows a linear, step-by-step structure, possibly spanning multiple sessions or modules.
The document is a standalone piece, providing straightforward steps that can be followed in one sitting.
End Goal
The end goal of the document is to educate the user providing a foundational understanding.
The end goal of the document is to enable the user to perform a specific task or solve a particular problem.
Level of Detail
Does it include detailed explanations and background information? (Tutorial)
Does it focus on delivering concise, action-oriented instructions? (How-to)
Examples and Practical Application
The document includes examples to illustrate a process or concept in a broader learning context.
The document provides practical examples or scenarios specifically tailored to executing a task.
Analyzing Your Selections
Depending on how many times you have selected 1 or 2 your document will likely fit either a Tutorial or a How-to type of documentation:
If 1 is your selection for all documentation aspects, then your document is a Tutorial.
If 2 is your selection for all the documentation aspects, then your document is a How-to guide.
However, if you have selected 1 and 2, you may need to refine your documentation draft and reassess your documentation needs.
Last updated