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.