Introduction

Welcome to the SnapBench Author Guide. This section will help you create engaging, hands-on learning experiences for your participants.

Philosophy

SnapBench is built on a simple principle: learning by doing is more effective than learning by reading.

Traditional documentation and tutorials often fall short because:

• Readers don't have a ready environment to practice
• Setup instructions get outdated or fail on different systems
• There's no feedback loop to verify understanding

SnapBench solves this by providing real, isolated environments where participants can experiment safely with actual infrastructure.

What Authors Create

As an author, you design scenarios—interactive labs that combine components and instructions.

Element	Purpose
Components	Real infrastructure (databases, message queues, services)
Instructions	Interactive step-by-step guidance

When a participant starts your scenario (this is called a run), SnapBench:

1. Creates an isolated Kubernetes namespace
2. Deploys all components automatically
3. Provides terminal and web UI access
4. Displays interactive instructions alongside the running environment

The Author Workflow

┌─────────────────────────────────────────────────────────────┐
│  1. Design your scenario                                     │
│     • What should participants learn?                        │
│     • What components do they need?                          │
│     • What steps will guide them?                            │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  2. Build in the Studio                                      │
│     • Add components from the Catalog                        │
│     • Configure them for the target environment              │
│     • Write clear, actionable instructions                   │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  3. Test and iterate                                         │
│     • Run the scenario yourself                              │
│     • Verify all steps work                                  │
│     • Refine based on feedback                               │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  4. Publish and organize                                     │
│     • Publish the scenario                                   │
│     • Add to tracks for structured learning paths            │
│     • Assign to participants                                 │
└─────────────────────────────────────────────────────────────┘

Key Principles for Effective Scenarios

1. Start with the Learning Objective

Before building, ask: "What should participants be able to do after completing this lab?"

Good objectives are specific and actionable:

• "Create a Kafka topic and produce messages" (specific)
• "Understand Kafka" (too vague)

2. Provide Real Infrastructure

Don't simulate—use actual components. Participants learn better when they interact with real PostgreSQL, real Kafka, real Elasticsearch.

3. Guide, Don't Prescribe

Good instructions explain the "why" alongside the "what". Help participants understand concepts, not just copy commands.

4. Design for Recovery

Participants will make mistakes. Design scenarios that are resilient:

• Include troubleshooting tips
• Provide ways to verify success
• Consider what happens if steps are done out of order

5. Respect Time

Most participants have limited time. Design scenarios that:

• Can be completed in the allocated TTL
• Have clear milestones
• Don't include unnecessary steps

What's Next

1. Core Concepts — Understand components, scenarios, runs, and tracks
2. Catalog & Components — Learn about available components
3. Tracks & Scenarios — Organize your content
4. The Studio — Master the authoring interface
5. Writing Instructions — Create engaging guidance
6. Best Practices — Tips and troubleshooting