Skip to content

Tutorial_Content_Template.md

Latest commit

 

History

History
84 lines (62 loc) · 2.87 KB

Tutorial_Content_Template.md

File metadata and controls

84 lines (62 loc) · 2.87 KB
Raw

1. Introduction (Motivation & Context)

A tutorial should always start with a clear objective – and ideally with a small spark of excitement.

Example:
“In this tutorial, you’ll learn how to publish your very first article in the CMS. By the end, your post will be live on the website – a small step in the tool, but a big leap in your communication work.”

Author’s note:

  • Provide a simple storyline: Who is doing what, and why?
  • State the concrete learning outcome clearly.
  • Keep the tone inviting, not dry.

2. Prerequisites (What Do I Need?)

Set out the minimal requirements before the user can begin.

Example:

  • Login credentials for the CMS
  • User role “Editor” or higher
  • Title and draft text for the article prepared in advance

Author’s note:

  • Only list what’s truly essential.
  • Short, clear, checklist style.

3. Step-by-Step Instructions (The Core)

This is the heart of the tutorial: clear, linear instructions with no detours into theory.

Example:

  1. Log in to the CMS.
  2. In the menu, go to Content → Posts.
  3. Click New Post.
  4. Enter the following details:
    • Title: “Welcome to our new CMS!”
    • Content: Paste in your prepared text
    • Image (optional): Upload via Add Media
  5. Click Save.
  6. To make your article visible, select Publish.

Author’s note:

  • Always use numbered, actionable steps.
  • Focus on doing, not explaining.
  • Each step should create something visible or verifiable.

4. Outcome (Reward & Confirmation)

Confirm the visible success at the end.

Example:
“Your article is now published and appears on the homepage. Well done – your CMS account has successfully launched its first live post!”

Author’s note:

  • Make sure the accomplishment is obvious and measurable.
  • Close with a rewarding and encouraging tone.

5. Further Links

This is where you connect to the other Diataxis documents.

Example:

  • How-to guide: “Editing a published article”
  • Explanation: “Why the CMS uses different publishing states”
  • Reference: “All field definitions for the Post module”

Author’s note:

  • Always link to at least one item of each type.
  • This is how a coherent documentation system is built.

Summary for Authors

A model Diataxis tutorial in the CMS context should always contain:

  1. A motivating start (Why does this matter?)
  2. A short prerequisites list (What do I need first?)
  3. A linear, step-by-step walkthrough
  4. A confirmation of success
  5. Cross-references to other document types

The goal: users don’t need to learn the entire CMS, they just need to succeed in one clearly defined scenario – ideally with a touch of satisfaction rather than frustration.