Catalog
concept#Software Engineering#Delivery#Integration#Product

Tutorial

Practice-oriented, step-by-step guidance for teaching concrete skills, typically including examples and exercises.

A tutorial is a practice-oriented guide that teaches step-by-step skills, tools, or workflows, typically including examples and exercises.
Established
Medium

Classification

  • Medium
  • Organizational
  • Organizational
  • Intermediate

Technical context

Repository hosting (e.g., GitHub)CI/CD pipelines for example executionDocumentation platforms (e.g., MkDocs)

Principles & goals

Goal orientation: Every tutorial starts with clear learning objectives.Practicality: Examples and exercises are hands-on and reproducible.Maintainability: Tutorials are versioned and easy to update.
Discovery
Team, Domain

Use cases & scenarios

Compromises

  • Incorrect or outdated guidance can lead to misconfigurations.
  • Excessive simplification can hide important details.
  • Unclear objectives cause frustration instead of progress.
  • Offer small, focused learning steps with immediate feedback.
  • Version tutorials and maintain change logs.
  • Set up automated tests for examples and code snippets.

I/O & resources

  • Target audience and learning objectives
  • Sample and test data
  • Access to relevant systems
  • Finished tutorial with exercises
  • Checklist for review and approval
  • Metrics for success measurement

Description

A tutorial is a practice-oriented guide that teaches step-by-step skills, tools, or workflows, typically including examples and exercises. It organizes learning objectives, prerequisites and success criteria to help teams disseminate knowledge consistently. Tutorials are versatile and require trade-offs between depth, scope and long-term maintainability.

✔

  • Accelerated onboarding of new team members.
  • Consistent knowledge transfer across teams.
  • Reduced support and ramp-up time via self-guided exercises.

✖

  • High effort to create comprehensive, up-to-date tutorials.
  • Suitability depends on audience and prior knowledge.
  • Can become outdated if not maintained.

  • Time to productivity

    Measure of how long users take to become productive after the tutorial.

  • User satisfaction

    Assessment of usefulness and clarity via feedback or surveys.

  • Update frequency

    How often the tutorial is maintained or adapted to changes.

Repository setup tutorial

Step-by-step guide for cloning, local build and testing of a project.

API consumer tutorial

Sample app that consumes API endpoints and demonstrates common error cases.

CI/CD onboarding tutorial

Guided steps to set up a pipeline, including tests and deployment.

1

Define audience and learning objectives

2

Structure content and create examples

3

Organize peer review and test runs

4

Publish and set up metrics

⚠️ Technical debt & bottlenecks

  • Manual sample data needs regular updates.
  • Missing automation of tests for code snippets.
  • Non-versioned tutorials hinder traceability.
Author capacityReview and approval processesTechnical infrastructure for examples
  • Using a tutorial to replace full training for critical operational topics.
  • Publishing tutorials without review leading to misinformation.
  • A tutorial covering too many unrelated aspects that confuse users.
  • Unclear prerequisites lead to wrong expectations.
  • Examples not automatically validated become outdated quickly.
  • Lack of audience orientation reduces learning effectiveness.
Domain expertise on the topicBasic instructional design skillsTechnical ability to reproduce examples
Repeatability of learning pathsMaintainability and versioningAccessibility for target audiences
  • • Limited authoring and review resources
  • • Dependencies on internal product changes
  • • Requirement for consistent versioning