Professional Content Management

Free and open source, TYPO3 CMS is the most widely used enterprise-level CMS.

Test TYPO3 now:

TYPO3 live demo

Inspire people to share

Offer your skills and contribute to the project. The community is growing and does more than just coding. 

A Community Effort

TYPO3 CMS is an Open Source project managed by the TYPO3 Association.

The Project

Do you have a question?

Ask the community or a professional partner.

Contribute to Step‑by‑Step Guides — a New Way to Learn TYPO3 Hands‑On

Categories: Association, Documentation Created by Mathias Bolt Lesniak
A screenshot of a TYPO3 documentation page titled Create a Page with Drag and Drop, featuring step-by-step guides, prerequisites, and a navigation menu on the left. The main content discusses tools, technology, and required knowledge.
The Step-by-Step Guides are designed for action — to help newcomers and intermediates accomplish tasks directly, and to do so reliably.
Step‑by‑Step Guides are hands-on tutorials focused on completing a single, practical task from start to finish. Here’s what they are, how they differ from traditional documentation, and why they can be a go-to resource when learning or contributing to TYPO3.

Step-by-Step Guides is a simple concept created for TYPO3 by documentation experts, based on a need faced by the TYPO3 Community Expansion Committee: Practical exercises for learning on your own, with a mentor, or in a classroom. You may also recognize the need from your own work.

Practical Exercises for Learning

How do you make new employees productive quickly? How do you know which skills are essential right now and which ones you can teach later? These are central questions, not only when onboarding juniors into an agency, but also when the Community Expansion Committee teaches local web developers how to build government websites in the Global South.

The TYPO3 Onboarding Curriculum was the committee’s first outcome: A lesson-by-lesson training program outline, ready to be adapted and used for their training. But it only defines prerequisites and goals for each lesson. Between itself and the exhaustive TYPO3 documentation, it lacks instructions on what to teach and how. Step-by-Step Guides solve this problem, and we think they can help anyone learning or teaching TYPO3.

Because they are modular, each guide stands alone. But they can also be composed: Multiple guides together can form larger tutorials or workshops. This makes them flexible for both self‑led learning and organized curricula.

Step‑by‑Step Guides: Single Goal and Clear Actions

The Step-by-Step Guides are designed for action — to help newcomers and intermediates accomplish tasks directly, and to do so reliably.

Shaped as guided walkthroughs, you do the work as you read, so it’s not just observing or reading theory. The goal is to enable someone to follow along and reach a successful, repeatable result.

The guides are inspired by the Diátaxis framework, which separates documentation types into categories like tutorials, how‑tos, reference, etc. In this framework, step‑by‑step guides align with the tutorials style: structured, sequential, and focused on doing.

A 2x2 grid divides content types: Tutorials (learning, action), How-To Guides (goals, action), Explanation (understanding, cognition), and Reference (information, cognition). A label highlights Step-by-Step Guides for TYPO3.
The Diátaxis framework, which separates documentation types into categories like tutorials, how‑tos, reference, etc. Step‑by‑step guides align with the tutorials style. Source: diataxis.fr

Key Principles of TYPO3 Step‑by‑Step Guides

TYPO3’s Step‑by‑Step Guides follow several guiding principles to ensure they are effective:

  • Hands‑on learning: You learn fastest by doing, i.e. working through concrete steps rather than reading abstract theory.
  • One clear path: No branching paths or optional detours. The guide leads you through a single method that works reliably.
  • Minimal, but sufficient explanation: Only explain what is strictly needed to keep the learner moving. For deeper context, readers are encouraged via links to the more detailed/explanatory material.
  • Visible, reliable progress: Each step should produce visible change (something you can check), and at the end the outcome should be repeatable.
  • Small time commitment: Each guide should take less than 30 minutes to complete.

The guides must also align with TYPO3’s other documentation. They stay focused by linking to relevant in‑depth reference material or theory as needed, and do not try to replicate it.

What Step‑by‑Step Guides Are Not

To avoid confusion, it’s helpful to clarify what these guides aren’t:

  • They are not a replacement for documentation. They are a complimentary action-oriented and practical addition to the in-depth reference docs, explanations, and configurations of TYPO3’s existing documentation.
  • They are not examples or case studies. Examples are often used in documentation for illustration, but they are generally read, not followed step by step. Step‑by‑step guides expect action.
  • They are not explorations of many paths. They don’t cover every possible scenario, configuration, or optional branch. They focus on one path that works.

Why Use a Step‑by‑Step Guide?

  • Faster onboarding for new editors, developers, and integrators: you can start doing, rather than learning passively.
  • Confidence building: by completing something reliably, you see tangible results, which helps understanding.
  • Reduced friction: less searching for which piece of theory applies, fewer misunderstandings, since each step is prescriptive.
  • Consistency: When many guides follow the same style and structure, users know what to expect.

For Contributors: Good Instructions Make Good Guides

Contributing your own Step-by-Step Guide is supposed to be easy. The Contributor Guide contains all you need to know — and much good advice as well. On top of that, the guides are written in MarkDown, so formatting options are deliberately kept as simple as the content of your guide should be.

Documentation expert Felicity Brand has created two videos explaining some of the basics. For beginners who want to contribute through their browser only, there is also a step-by-step guide about how to Contributing a Step-by-Step Guide Using Your Browser and GitHub.

A woman with glasses speaks in the bottom left corner of an orange screen displaying the text Introducing TYPO3 Step-by-Step Guides with a play button overlay. The TYPO3 logo is in the top right corner.
Play Felicity's introduction video for Step-by-Step guides.
A paused video titled Using the template: TYPO3 Step-by-Step Guides has an orange background. A woman with glasses appears in the bottom left corner. The TYPO3 logo and website link are visible.
Learn how to use the step-by-step guide template in this video by Felicity Brand.

If you’re interested in writing or improving a step‑by‑step guide, here are some tips:

  • Pick a single learning objective. Don’t try to cover multi‑task workflows.
  • Keep explanations short, link out for theory or details.
  • Make every step produce something visual or verifiable.
  • Test the guide: follow it yourself (or have someone else follow it) from start to finish to ensure it works.
  • Stick to the time guideline: Aim for under 30 minutes. A guide that’s quick to follow will also be quick to write.

To help track missing guides, links to non-existent guides are tracked and listed as guides you can contribute.

Filling a Space

Learning TYPO3 should be practical, accessible, and efficient. Step-by-Step Guides help people do real things with TYPO3 quickly, while leaning on existing documentation for depth. Whether you’re a new integrator, a developer exploring extension work, or simply someone wanting to try something hands-on, these guides are crafted for you.

Take a moment to explore the Step‑by‑Step Guides registry. Work on the guides has just commenced, but with your help, we hope you’ll soon find practical steps covering everything from installation to extension development — all structured to help you get results fast.

Additional contributors for this article

Related News

Latest news

Show more