docs-creating-by-example-tutorials

By-Example Tutorial Creation Skill

Purpose

This Skill provides comprehensive guidance for creating by-example tutorials - a code-first learning path designed for experienced developers who want rapid language pickup through heavily annotated working code examples.

When to use this Skill: creating by-example tutorials for programming languages, writing heavily annotated code examples, designing code-first learning paths achieving 95% language coverage, or meeting annotation density standards (1.0-2.25 comments per code line).

Core Concepts

What is By-Example?

By-example tutorials are a code-first learning path that achieves 95% language coverage through 75-85 heavily annotated, self-contained code examples.

NOT a replacement for:

• Beginner tutorials (which provide deep explanations for complete beginners)
• Quick Start (which is 5-30% coverage touchpoints)
• Cookbook (which is problem-solving oriented, not learning-oriented)

Target Audience: Experienced developers who already know at least one programming language well, want quick pickup through working code rather than extensive narrative, and need ~90% coverage efficiently.

Five-Part Example Structure

Each example follows a consistent five-part structure:

### Example N: Concept Name

**Brief explanation** (1-3 sentences describing what this example demonstrates)

**Optional diagram** (Mermaid diagram if concept relationships complex)

**Heavily commented code** (self-contained, runnable example with educational annotations)

**Key takeaway** (1-2 sentences summarizing the lesson)

Annotation Density Standards

See Annotation Density Standards for the 1.0-2.25 rule, the density calculation formula, the // => annotation pattern with worked Java/Python examples, and the quality-over-quantity guidance.

Self-Containment Rules and Comparisons

See Self-Containment Rules and Comparisons for what makes an example self-contained, how to achieve it, and the multiple-code-blocks pattern for comparison examples.