Documentation/Tutorials

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

• API:Nearby places viewer
• API:Article ideas generator
• API:Picture of the day viewer
• API:Holidays viewer
• API:Presenting Wikidata knowledge
• API:Page info in search results
• Manual:Pywikibot/PAWS
• Gadget kitchen
• wikidata:Wikidata:Pywikibot - Python 3 Tutorial
• wikitech:Portal:Toolforge/Quickstart
• wikitech:Help:Toolforge/My first Django OAuth tool
• wikitech:Help:Toolforge/My first Flask OAuth tool
• wikitech:Help:Toolforge/My first NodeJS OAuth tool
• wikitech:Help:Toolforge/My first Pywikibot tool
• wikitech:Help:Toolforge/My first Rust tool
• OOUI Basics part 1
• OOUI Basics part 2
• Search Wikipedia articles
• Explore page history
• Reuse media files from Wikimedia Commons
• Wikidata Query Service tutorial

Collections

• Category:Tutorials
• Wikimedia tutorials
• wikitech:Category:Tutorials

Tools for creating tutorials

• wikitech:PAWS

Description

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.

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

Introduction

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

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

Numbered steps

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

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

Commands and examples should be tested for accuracy.

Review process

Review a tutorial on Phabricator

See the checklist