Documentation

tutorials/README.md

About Tutorials

What's Here

Learning-oriented documentation that teaches fundamental concepts through hands-on lessons.

Current tutorials:

  • getting-started.md - First steps with Dynaplex
  • your-first-component.md - Build a simple component from scratch
  • local-setup.md - Set up your development environment

What Belongs Here

Tutorials are lessons that:

  • Take learners by the hand through a series of steps
  • Help beginners acquire basic competence
  • Show how to get started with Dynaplex
  • Are safe, reliable, and work every time

Examples of good tutorials:

  • "Build your first microservice"
  • "Deploy a component to Azure"
  • "Set up debugging for Aspire services"
  • "Create your first database migration"

What Doesn't Belong Here

❌ Problem-solving guides → Use how-to/
❌ Reference documentation → Use reference/
❌ Conceptual explanations → Use explanation/
❌ Production operations → Use operations/

How to Think About This

Analogy: Teaching a child to cook

  • Tutorial: "Let's make scrambled eggs together. First, crack the egg..."
  • Not a tutorial: "To cook eggs, you need heat" (that's explanation)
  • Not a tutorial: "How to fix runny eggs" (that's how-to)

Key characteristics:

  • For beginners - Assume no prior knowledge
  • Learning by doing - Hands-on, practical
  • Complete and self-contained - Everything needed is included
  • Minimum necessary - Don't explain everything, just enough to learn
  • Build confidence - Success is guaranteed if steps are followed

Writing Guidelines

Structure

  1. Clear goal - "By the end, you'll have built..."
  2. Prerequisites - Tools/knowledge needed
  3. Step-by-step instructions - Numbered, sequential
  4. Expected results - "You should see..."
  5. Next steps - Where to go from here

Style

  • Use second person ("you will...")
  • Be encouraging and supportive
  • Explain what to do, not necessarily why
  • Show concrete examples
  • Test thoroughly - tutorials must work!

Example Template

# Tutorial: [Specific Goal]

Learn [skill] by building [thing].

## Prerequisites
- [Tool/knowledge needed]

## What You'll Build
[Describe end result]

## Step 1: [Action]
[Instructions]

You should see:
[Expected output]

## Step 2: [Action]
...

## What You Learned
- [Skill/concept]
- [Skill/concept]

## Next Steps
- [Related how-to]
- [Related tutorial]

When to Create a Tutorial

Create a tutorial when:

  • ✅ There's a fundamental skill beginners need to learn
  • ✅ The learning is best done through practice
  • ✅ You can provide a safe, controlled environment
  • ✅ Success can be guaranteed through clear steps

Don't create a tutorial when:

  • ❌ The task is too specific (use how-to instead)
  • ❌ It's reference information (use reference instead)
  • ❌ It's explaining concepts (use explanation instead)

Diátaxis Quadrant

Tutorials are:

  • Practical (doing) not theoretical
  • Focused on learning not achieving a specific goal
  • Study-oriented not task-oriented
  • Introductory not comprehensive

Questions? See Documentation Setup