Tutorials
Disclaimer: This page contains my personal reading notes on the Diátaxis documentation framework.
What this notes cover &#xNAN;My learning notes about tutorials in the Diátaxis documentation framework.
Overview
Tutorials are a learning-oriented documentation type. Tutorials enclose practical knowledge to allow users to learn about a very specific and first-level topic. Tutorials are lessons that:
”must help a beginner achieve basic competence with a product so that they can go on to use the product for their purposes.”
Tutorials turn new learners into users and, because of that, are entitled to the “glorious purpose” of providing a first successful experience of the product. To do so, tutorials have to provide:
A complete overview of the expected result
Meaningful information
Steps to succeed that:
Are specific and complete
Appear in the right order
Come in the right context
Characteristics
Tutorials are learning-oriented so they provide a learning experience. This learning experience MUST avoid:
Extensive explanations, abstractions, and generalizations
Present choices and information
In other words, tutorials are lessons with a teacher and a learner, each of them with their specific responsibilities:
The teacher writes the tutorial and commits to showing just the required instructions for the learner to succeed.
The learner has to do as instructed.
After completing a tutorial, users should see results immediately and “be able to start to make sense of the rest of the documentation and the product itself”.
A Tutorial Example: The Incredible Platform
Getting Started with the Incredible Platform
To start with the Incredible Platform you need your user account and apply the common security configuration. In this tutorial, you will learn all the steps you need to access the Incredible Platform resources and tools for your product team.
Prerequisites
Accessing the Incredible Platform
To access the Incredible platform follow these steps:
Connect to the Incredible Platform’s VPN using your user account.
Open www.weareincredible.com.
Provide your Incredible username and password.
Read the Incredible terms and conditions.
Accept the terms and conditions to close the window.
After completing these steps, the Incredible home page will open showing two buttons:
Product Development: Incredible Platform features and resources
Platform Configuration: options to configure your product requirements and scope.
Applying the Common Security Configuration
Now that you are logged in to the Incredible Platform, apply a common security configuration for all your future products. To do so follow these steps:
Select Platform Configuration.
Go to Security and Backup > Product settings.
Confirm that your username and product name are correct.
Provide all the required information about your product and team.
Set a Backup Periodicity.
Select Save and Close.
Congratulations! Your user is now active in the Incredible Platform.
Last updated