documentation-tutorial

name

documentation-tutorial

description

Build hands-on, code-first tutorials from any primary source - technical documentation, codebases, APIs, tools, or other complex material. Extract real examples, working code, and concrete scenarios. Create tutorials using markdown (text-heavy summaries) or React artifacts (complex interactive workflows). Keywords - tutorial, codebase, API, hands-on, code-first, copy-paste, interactive, real examples, primary source

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: Thesys C1 API (React Artifact)

Why React: Complex API needing interactive tabs/navigation

Structure: Setup (5min) → First Call → Core Operations → SDK Examples → Real Scenario → Advanced → Troubleshooting

Key Features: Sidebar navigation, copy buttons, tabbed views, real data, workflow chaining

Academic Study Guides: Quote Integration

Same principle applies to academic primary sources (historical documents, philosophical texts, legal cases): transform into practical guide.

Core Principle

Embed quotes throughout analysis where they support arguments. NOT collected at end.

Pattern

Question → Quote → Interpretation → Quote → Synthesis

NOT: Question → Summary → All Quotes at End

Example

## Was Qianlong's Response Wise?

Qianlong defended sovereignty. He explained:

> "If other nations imitate your evil example... how could I possibly comply?"

His reasoning was sound: granting Britain privileges would force him to grant all nations the same.

However, his rejection showed complacency:

> "Strange and costly objects do not interest me."

By dismissing British technology, he missed intelligence-gathering opportunities.

Debate Format

1. Clear position
2. 8-10 numbered arguments (each with quote evidence)
3. Rebuttals section
4. Conclusion

Each argument: Claim → Quote → Interpret → Connect to thesis

Checklist

• Quotes embedded at point of analysis
• Every claim supported by quote
• Each quote followed by interpretation
• Creates "guide through sources"

File Organization

CRITICAL: All tutorials follow this organization pattern:

1. Markdown Tutorials → claude_files/tutorial/

# Create in project's claude_files/tutorial directory
mkdir -p claude_files/tutorial

# Create tutorial file there
# Example: claude_files/tutorial/youtube-data-api.md

Naming convention:

• Lowercase, kebab-case
• Descriptive: {technology}-{purpose}.md
• Examples: youtube-data-api.md, python-cli-tutorial.md, docker-compose-guide.md

2. HTML Tutorials → claude_files/html/

# Create in project's claude_files/html directory
mkdir -p claude_files/html

# Create HTML file there
# Example: claude_files/html/youtube-data-tutorial.html

Naming convention:

• Lowercase, kebab-case
• Descriptive: {technology}-{purpose}.html
• Examples: youtube-data-tutorial.html, api-comparison.html

3. Why This Pattern?

1. Project-specific - Tutorials live with the code they document
2. Version controlled - Part of the project, tracked in git
3. Self-contained - Everything in claude_files/ for easy cleanup
4. Consistent location - Always claude_files/tutorial/ or claude_files/html/
5. No symlinks - Direct files, no complicated linking

Workflow

When creating a tutorial:

Markdown:

1. Run: mkdir -p claude_files/tutorial
2. Create: claude_files/tutorial/{name}.md
3. Preview: nvim -c "MarkdownPreview" claude_files/tutorial/{name}.md

HTML:

1. Run: mkdir -p claude_files/html
2. Create: claude_files/html/{name}.html
3. Open: open claude_files/html/{name}.html

Tools & Preview

Build: building-artifacts skill (React + Tailwind + shadcn/ui) Format: Dark code blocks with copy buttons, monospace Layout: Sidebar + main content

Preview markdown tutorials:

CRITICAL: Always open markdown tutorials with preview immediately after creation.

nvim -c "MarkdownPreview" /path/to/tutorial.md

This provides instant visual feedback and allows the user to review formatting, code blocks, and overall structure in the rendered view.

Use direct commands (no aliases) for reproducibility.