Jump to content

Documentation/Tutorials

From mediawiki.org

A tutorial provides a learning experience, in which the the learner follows the close guidance of a teacher.

Tutorials should be:

  • clear about prerequisites
  • ordered
  • reproducible

Examples

[edit]

Collections

[edit]

Tools for creating tutorials

[edit]

Description

[edit]

Tutorials are lessons that take the reader through a series of steps to complete some sort of meaningful project. Tutorials are learning-oriented, and allow the learner to encounter and work with the tools, processes, concepts, vocabulary of the domain in a safe context.[1]

In a tutorial, the tutor is always in charge and knows in advance what will happen. What matters in a tutorial is not what is accomplished, or how well, but what the user will learn through the experience.

Required

[edit]

Introduction

[edit]

The first section under the title should introduce the topic and audience of the page and provide a clear description of what the reader can expect to accomplish by following the guide.

Prerequisites

[edit]

The page should include a "Prerequisites" section that describes the required tools, knowledge, or other prerequisites required to complete the tutorial.

Numbered steps

[edit]

Section headings should be numbered to emphasise that the user is to follow the tutor's guidance closely, should and represent a clear sequence of steps.

Set expectations and verify success

[edit]

A tutorial should provide psychological safety, so that the learner does not expend mental energy trying to understand whether things are going well or not. "When you do x you should notice y" or "Observe that ..." help reassure the learner, and also draw their attention to important signs in their working environment.

Working examples

[edit]

Commands and examples should be tested for accuracy.

Review process

[edit]

References

[edit]