documentation-tutorial

What this skill does

# Tutorial Developer from Primary Sources

Transform any primary source into hands-on, practical tutorials that prioritize real, working examples over conceptual explanations. Focus on what users need to *do*, not what they need to understand.

## Quick Decision Guide

**Step 1: Choose format**
- Text-heavy summary or CLI reference → Markdown
- Complex workflow with multiple steps → React Artifact

**Step 2: Follow the three pillars**
1. Real code/commands (not pseudocode)
2. Real use cases (concrete scenarios)
3. Mental model (one-sentence explanation)

## Core Principles

### The Three Pillars

Every tutorial must clearly answer:

1. **Real Code**: What's the actual code or command I run? (Copy-paste executable, no pseudocode)
2. **Real Use Cases**: When would I actually use this? (Concrete scenarios like "healthcare bot", not vague descriptions)
3. **Mental Model**: How does this work? (One-sentence explanation enabling independent problem-solving)

**Example:**
```
Mental Model: "AI generates interactive React components from natural language prompts, streaming in real-time."

Code:
curl -X POST https://api.thesys.dev/v1/ui/generate \
  -H "Authorization: Bearer sk-thesys-key" \
  -d '{"prompt": "Create a booking form", "model": "gpt-4"}'

Use Case: When you want users to book appointments without writing React,
send a prompt and stream the form directly into the page.
```

### Code-First Approach

- Lead with working examples, not theory
- Real endpoints (actual URLs, not `<placeholder>`)
- Exact payloads (complete JSON, not simplified)
- No high-level summaries unless essential
- Get users to running code within 5 minutes

## Systematic Workflow

### Phase 1: Extract from Primary Source

**Step 1: Identify Core Mental Model**

Answer: *"What's the one-sentence explanation that makes everything click?"*

Examples:
- API: "AI generates interactive UIs from prompts, streaming real-time"
- Tool: "PDFs are structured data; extract tables/text like CSV/JSON"
- Codebase: "Request flows through middleware → router → handler → response"
- Academic Paper: "YouTube Data API v3 lets you search videos, get metadata, and filter by captions/views/category using REST endpoints"

### Primary Source Types

**Documentation:** Official API docs, SDK references, CLI manuals

**Codebases:** Open source projects, example repos

**Tools:** Software applications, command-line utilities

**Academic Papers:** Research methodologies in appendices/supplementary materials
- Look for: Data collection procedures, API workflows, filtering criteria, implementation details
- Example: MINEDOJO paper Appendix D.1 documents exact YouTube API usage with 5-step workflow
- Extract: Step-by-step procedures, quota limits, legal considerations, real filtering parameters
- Value: More rigorous methodology than typical blog posts, validated by peer review

**Step 2: Find Real Examples**

Extract from docs/code:
- Working code (not pseudocode)
- CLI commands with actual flags
- API calls (curl + request/response)
- Config files, error cases

**Step 3: Extract Concrete Use Cases**

❌ **Wrong:** "Can be used for various applications like analytics, reporting, etc."

✅ **Right:**
1. **Analytics Dashboard**: User asks "show me sales by region" → AI generates chart
2. **Booking Flow**: Customer books appointment → form auto-generates with calendar
3. **Support Tickets**: Agent asks "show ticket queue" → interactive table generates

For each: What triggers it, what code is needed, what user sees, why it matters.

### Phase 2: Structure Tutorial

**Step 4: Plan Sections** (Action-oriented names)
- Section 1: "⚙️ Setup & Install" → Running in 5 minutes
- Section 2: "🚀 First API Call" → Verify it works
- Section 3: "🌐 Core Operations" → Major endpoints
- Section 4: "🐍 SDK Examples" → Language-specific code
- Section 5: "💾 Real Scenario" → Complete workflow

**Step 5: Plan Code Blocks**
- Copy-paste executable curl with real endpoint
- Tabs: cURL → Request Body → Response
- Real data values (names, dates, actual fields)
- Error cases if documented

**Step 6: Plan Workflow**
- Choose actual use case from documentation
- Break into 3-5 sequential API calls
- Show how responses flow into next step

### Phase 3: Implement

**Step 7: For React Artifacts**

Structure:
- Sidebar navigation (6-8 focused sections)
- Main content area with code blocks
- Copy buttons on all code
- Tabbed views (curl/request/response)

**Step 8: Code Block Spec**
- Dark background, language label, copy button
- Left-aligned monospace, syntax highlighting
- No line numbers (confuses copy-paste)

**Step 9: Quality Check** (see checklist at end)

## Tutorial Patterns

### Pattern: API Endpoints
```
TITLE: Endpoint Name (POST /v1/endpoint)
DESCRIPTION: One sentence
CODE BLOCK: Tabs (cURL | Request | Response)
USE CASE: One sentence + real scenario
```

### Pattern: Complete Workflows
```
STEP 1: First API Call
  Context (1 sentence) → Code → Result
STEP 2: Second API Call
  Context (how previous flows here) → Code → Result
STEP 3: Final Outcome
```

### Pattern: Setup/Installation
```
PREREQUISITES: What they need
COMMAND: Full copy-paste command
VERIFY: One-line check
TROUBLESHOOTING: Common issues
```

### Pattern: SDK Examples
```
LANGUAGE: Python/JavaScript/etc
CODE: Full working function (imports, async/await, error handling)
RUN IT: How to execute
OUTPUT: Expected result
```

### Pattern: Sidebar Navigation
- 6-8 focused sections (not monolithic)
- Emoji + action verbs: "⚙️ Setup", "🚀 First Call"
- Reduces cognitive load, improves completion

### Pattern: Copy Buttons
- One-click copy-to-clipboard (right corner)
- Visual feedback when copied (checkmark, 2 seconds)
- 3x higher code execution rate

### Pattern: Mental Models First
- Present one-sentence model after first working example
- Place in colored box: "💡 How This Works"
- Enables independent problem-solving

### Pattern: Progressive Disclosure
- Section 1: Minimum to get running
- Section 2: Simplest successful request
- Section 3-4: Core operations, multiple languages
- Section 5: Complete multi-step workflow
- Section 6: Advanced features
- Section 7: Troubleshooting

### Pattern: Concrete Use Cases
```
## Common Use Cases

1. **Analytics Dashboard** (5 min read)
   You want users to ask "show me Q3 revenue"
   → AI generates interactive chart

2. **Booking Form** (7 min read)
   You need booking flow without React
   → AI generates form with calendar

[Pick your use case →]
```

Benefit: Users self-select relevant tutorial path.

### Pattern: Troubleshooting
- Color-coded sections (red=critical, yellow=common)
- For each: Problem → Root cause → Solution → Code
- Include CORS, auth failures, timeouts

## Quality Checklist

**Three Pillars:**
- [ ] Real code (copy-paste executable: curl, Python, JavaScript)
- [ ] Real use cases (3-5 concrete scenarios, not "theoretical")
- [ ] Mental model (one-sentence explanation)

**Code Quality:**
- [ ] Real endpoints (no `<placeholder>`)
- [ ] Real data (Sarah Chen, 2025-11-15, actual field names)
- [ ] Tabs: cURL + Request + Response
- [ ] Left-aligned, properly formatted

**Structure:**
- [ ] First section: Running code in <5 minutes
- [ ] 6-8 focused sections with navigation
- [ ] Complete workflow (form → submit → confirm)
- [ ] Multiple languages (Python, JavaScript, HTTP)

**Content:**
- [ ] Mental model within first 2 examples
- [ ] No conceptual fluff or "learning objectives"
- [ ] Real-world scenario shows data flowing
- [ ] Troubleshooting with real problems

**Interactive (for React artifacts):**
- [ ] Copy buttons on all code
- [ ] Users can complete real task after tutorial

## Real Examples

### Example 1: Mail Command (Markdown)
**Why Markdown:** CLI reference with many commands

**Structure:** Basic Sending → Advanced Options → Interactive Mode → Reading Mail → Configuration → Gmail Integration → Quick Reference

**Key Features:** Copy-paste commands, real config files, organized by workflow

### Example 2