What are step-by-step guides?
TYPO3 step-by-step guides are hands-on tutorials designed to help newcomers accomplish one practical task.
Inspired by the Diátaxis framework, which emphasizes distinct content types in technical documentation, step-by-step guides map to the “tutorials” category.
TYPO3 step-by-step guides follow a few key principles:
- Hands-on learning: The fastest way to learn is by doing.
- One clear path: No branches - just one method that works, from start to finish.
- Minimal explanation: Explain only what’s necessary to keep someone moving. Link out for deeper context.
- A successful finish: Every step produces visible progress, and the outcome is reliable and repeatable.
- Aligned with TYPO3’s official documentation: linking out to deeper material as needed
- Takes less than 30 minutes to complete
A good step-by-step guide follows the single-responsibility principle (SRP): it should do one thing, and do it well. > Every step contributes directly to a single learning objective, and nothing more.
If you find yourself adding “If…” or “Alternatively…”, the guide may violate the single-responsibility principle.
What are they not?
Step-by-step guides aren’t examples. Examples are usually found in the documentation, and help to illustrate concepts - they are meant to be studied and understood. Guides, in contrast, take the reader through a path of sequential steps, and are designed to be actively followed to learn a new concept.
Modular by design
Step-by-step guides are modular. Each guide is an atomic unit of action — small, focused, and self-contained, with one learning objective and one clear outcome. Guides can be combined to form larger tutorials or workshops, or used independently for self-led learning.
How do step-by-step guides fit in the existing TYPO3 documentation ecosystem?
TYPO3 documentation | Step-by-step guide |
---|---|
Information oriented Supports exploration and problem-solving for people seeking answers or understanding.. | Learning oriented Helps people learn through hands-on experience. |
Comprehensive Presents various approaches, configurations, and possibilities. Also covers edge cases. | Single clear path Follows a carefully managed path from start to finish with guaranteed success. |
Blends doing and explaining Combines how-to instructions, explanations, and reference information. | Focused on doing Prioritizes action with minimal explanation; links out to deeper material in the docs. |