Skill: tutorial-writing

What I do

I provide expertise in crafting step-by-step learning guides and tutorials for teaching technical concepts. I focus on the Diátaxis tutorial format, prerequisite declaration, and expected outcomes per step.

When to use me

• Creating a "getting started" guide for a new project
• Writing a step-by-step tutorial for a specific feature or workflow
• Developing a training manual or workshop material
• Onboarding new developers to a codebase or technology

Core principles

1. Diátaxis Tutorial Format — Focus on learning by doing. The goal is to get the user to a successful result quickly.
2. Prerequisite Declaration — Clearly state any required tools, versions, and existing knowledge.
3. Step-by-Step Structure — Use logical, incremental steps with clear headings.
4. Expected Outcomes — Describe what the user should see or experience at the end of each step.
5. Troubleshooting — Anticipate common mistakes and provide solutions or pointers.

Patterns & examples

Tutorial Outline Template

• Title: Action-oriented (e.g., "Building a Simple API in Node.js").
• Intro: What will be built and what the reader will learn.
• Prerequisites: Tools and knowledge needed.
• Step 1: Set Up: Environment configuration.
• Step 2: Core Logic: Implementing the main feature.
• Step 3: Test & Verify: How to check the result.
• Summary: Recap and next steps.

Verification Step Pattern

"Run the following command in your terminal:"

npm start

"You should see the message Server running on port 3000. If you see an error about port already in use, try changing the port in config.js."

Anti-patterns to avoid

• ❌ Implicit Steps — Assuming the user knows how to perform an action without explaining it.
• ❌ Giant Code Dumps — Providing the final solution without explaining how it was built.
• ❌ No Verification — Failing to include steps for the user to verify their progress.
• ❌ Irrelevant Theory — Including long explanations that distract from the learning-by-doing goal.

KB Reference

~/vaults/baphled/3. Resources/Knowledge Base/AI Development System/Skills/Communication-Writing/Tutorial Writing.md

Related skills

• documentation-writing — For general technical clarity.
• writing-style — To maintain a consistent professional voice.
• proof-reader — For final clarity and correctness checks.
• mentoring — For constructive technical communication.