Example design

Example Design

Create code examples that teach effectively through progressive complexity.

Decision Tree: Which Example Type?

What does the user need?
├─ Show a single concept → Snippet (5-15 lines)
├─ Working code for a feature → Complete example (20-50 lines)
├─ Step-by-step teaching → Tutorial (multi-file, progressive)
└─ Reference for production use → Reference app (full project)

Example Types

Type	Purpose	Length	When to Use
Snippet	Single concept	5-15 lines	Quick reference, API parameter demo
Complete example	Working code	20-50 lines	Feature walkthrough, integration demo
Tutorial	Step-by-step	Multi-file	Onboarding, learning path
Reference app	Production patterns	Full project	Architecture reference, starter template

Progressive Complexity

Level 1: Minimal (happy path)
   ↓
Level 2: Add configuration
   ↓
Level 3: Add error handling
   ↓
Level 4: Add edge cases
   ↓
Level 5: Production-ready

Each level must be runnable independently. Never skip a level — the reader needs the progression to build understanding incrementally.

Example Anatomy

# 1. Context: What this does
"""Fetch user data from API"""

# 2. Setup: Prerequisites
import requests

# 3. Core: Main concept (highlight this)
response = requests.get("/users/123")  # <-- Key line
user = response.json()

# 4. Result: Expected output
print(user["name"])  # Output: "Alice"

Quality Checklist

• Runnable: Copy-paste works without modifications
• Complete: All imports included, no hidden dependencies
• Minimal: No unrelated code, no ceremonial boilerplate
• Commented: Key lines explained, not every line
• Realistic: Uses real-world names, URLs, and patterns
• Tested: Verified working before publishing

Tutorial Structure

## Tutorial: [Goal]

**Time**: 10 min | **Level**: Beginner

### What you'll build
[Screenshot/description]

### Prerequisites
- [requirement 1]
- [requirement 2]

### Step 1: [Action]
[Explanation]
[Code]
[Expected result]

### Step 2: [Action]
...

### Next steps
- [Related tutorial]
- [Advanced topic]

Anti-Patterns

• Foo/bar variables — use realistic names that convey domain meaning; customerName teaches more than foo
• Missing imports — if the reader cannot copy-paste and run, the example fails its purpose
• Outdated syntax — examples lag behind API changes faster than any other documentation; verify against current version
• No expected output — the reader cannot verify their result is correct without seeing what success looks like
• Untested code — untested examples are wrong examples; always run before publishing
• Wall of code with no explanation — code without context is a source listing, not a teaching tool
• Showing only the happy path — real usage hits errors; show what happens when things go wrong (at least in progressive Level 3+)
• Over-abstracted examples — wrapping the concept in 3 layers of indirection obscures the point; keep the example direct

When to Use

• Creating API reference examples for each endpoint
• Building quickstart guides for a library or framework
• Writing runnable demos for a product feature
• Designing tutorial sequences for onboarding