cs249r_book/mlsysim/docs/tutorials/TEMPLATE.md

Tutorial Template — MLSys·im

This document defines the canonical structure for all MLSys·im tutorials. Every tutorial follows this template exactly. Consistency is pedagogical.

---

Design Principles

1. One tutorial = one core question. The title IS the question. Every cell exists to answer it.
2. Predict → Compute → Reflect. Before showing code output, tell the reader what to expect. After showing it, explain what it means. This is the learning cycle.
3. The "aha moment" is sacred. Every tutorial has exactly ONE insight that changes how the reader thinks. Frame it, build to it, land it in the Key Insight callout.
4. Real hardware, real models. No toy examples. Every tutorial uses published specs from the Zoo.
5. Code-first, prose-second. Keep prose tight. The insight comes from the numbers, not from reading paragraphs. Explanations serve the code, not the other way around.
6. Sub-30-second runtime. Every tutorial runs on a laptop in under 30 seconds. No GPU needed.

---

Canonical Structure

Every tutorial has exactly these sections, in this order:

---
title: "<Core Question as Statement>"
subtitle: "<One-sentence hook — what makes this surprising or important>"
description: "<2-sentence summary for search/SEO>"
---

## The Question                          ← 2-3 sentences framing WHY this matters
                                          No code. Pure motivation.

::: {.callout-note}
## Prerequisites
<What tutorials must be completed first. Link them.>
:::

::: {.callout-note}
## What You Will Learn
<Exactly 3–4 bullet points. Each starts with a verb. Measurable outcomes.>
:::

::: {.callout-tip}
## Background: <Concept Name>            ← Jargon explained for newcomers
<Define key terms needed for THIS tutorial. Keep it to one concept.>
:::

---

## 1. Setup                              ← Hidden import cell + visible 2-line import

## 2. <First Analysis Step>              ← Name describes what we DO, not what we learn
   - Code cell (3–8 lines, heavily commented)
   - Brief prose interpreting the output

## 3. <Second Analysis Step>             ← The sweep / comparison / composition
   - Code cell
   - Prose or callout interpreting the pattern

## 4. <The Reveal>                       ← Where the aha moment lands
   - Code cell showing the surprising result
   - KEY INSIGHT callout (see below)

::: {.callout-important}
## Key Insight
<1–3 sentences. The ONE thing the reader should remember from this tutorial.
This is the "tweet-length" summary. Bold the core claim.>
:::

## 5. <Extension / Composition>          ← OPTIONAL: chain another solver
   - Shows how this connects to the broader system

---

## Your Turn                             ← Always exactly 3 exercises

::: {.callout-caution}
## Exercises

**Exercise 1: Predict before you compute.**
<Always the first exercise. Forces the reader to form a hypothesis before running code.
Structure: predict → run → compare → explain the gap.>

**Exercise 2: Change one variable.**
<Modify a single parameter and predict the effect. Builds intuition for sensitivity.>

**Exercise 3: Connect to another domain.**
<Use a different solver or compose solvers. Shows that walls interact.>

**Self-check:** <One quick mental calculation to verify understanding.>
:::

---

## Key Takeaways

::: {.callout-tip}
## Summary
<Exactly 3–5 bullet points. Each maps to a "What You Will Learn" objective.
Use the same verb structure. The reader should be able to check them off.>
:::

---

## Next Steps
<3–4 links to related tutorials, organized by domain cluster.
Format: **[Tutorial Name](link)** — one-sentence description of what it adds.>

---

Callout Usage (Strict Rules)

Callout Type	Purpose	When to Use
{.callout-note}	Prerequisites, Background, What You Will Learn	Factual, informational
{.callout-tip}	Background concepts, Summary/Takeaways	Helpful context
{.callout-important}	Key Insight (the aha moment)	Exactly ONCE per tutorial
{.callout-caution}	Exercises	Always in "Your Turn" section
{.callout-warning}	Common mistakes / pitfalls	Only when there's a real trap

---

Code Cell Guidelines

• Hidden setup cell: Always first. #| echo: false + #| output: false. Uses importlib path hack for dev, shows clean pip install import after.
• Visible cells: 3–8 lines each. Every line has a comment or is self-explanatory.
• Output formatting: Use f-strings with aligned columns for tables. Always include units.
• Sweeps: Use a simple for loop with a print header. No pandas/matplotlib unless essential.
• Variable names: Use domain terms (model, hardware, fleet, solver, result).

---

Naming Convention

Tutorials are numbered by cluster:

tutorials/
├── index.qmd                    ← Cluster-organized landing page
├── 00_hello_roofline.qmd        ← Cluster 0: Start Here
├── 01_memory_wall.qmd           ← Cluster 1: Node
├── 02_two_phases.qmd            ← Cluster 1: Node
├── 03_kv_cache.qmd              ← Cluster 1: Node
├── 04_starving_the_gpu.qmd      ← Cluster 2: Data
├── 05_quantization.qmd          ← Cluster 3: Algorithm
├── 06_scaling_1000_gpus.qmd     ← Cluster 4: Fleet
├── 07_geography.qmd             ← Cluster 5: Ops
├── 08_nine_million_dollar.qmd   ← Cluster 5: Ops
├── 09_sensitivity.qmd           ← Cluster 6: Analysis
├── 10_gpu_vs_wafer.qmd          ← Cluster 6: Analysis
├── 12_full_stack_audit.qmd      ← Cluster 7: Capstone
└── extending.qmd                ← Developer appendix (unnumbered)

---

Domain Cluster Tags

Every tutorial's YAML front matter includes a categories field for cluster membership:

categories: ["node", "beginner"]       # Cluster 1, difficulty level
categories: ["fleet", "advanced"]      # Cluster 4, difficulty level
categories: ["capstone", "advanced"]   # Cluster 7, difficulty level

Valid clusters: start, node, data, algorithm, fleet, ops, analysis, capstone Valid levels: beginner, intermediate, advanced