---
name: interactive_textbook_building
description: "Build an interactive textbook by mapping concepts into a learning graph before writing, ordering chapters by dependency, embedding small simulations and worked examples, and aligning quizzes to the graph so gaps show up as missing nodes. Stack-neutral method with a learning graph worksheet and a dependency checker. Use when someone asks to create, plan, restructure, or fix an interactive textbook, digital textbook, executable book, or self-study text with embedded questions or simulations."
---

# Interactive Textbook Building

## Purpose

Build the book in the wrong order and you get the usual result: chapters written by topic, quizzes written at the end, and readers hitting ideas they were never given the pieces for. This skill reverses that order. Map the concepts first as a graph of prerequisites, order chapters from the graph, write assessment items before prose, and add interactivity only where it teaches a named node.

The graph is the contract. If a concept is not a node, the book does not claim to teach it. If a node has no quiz item, that is a visible gap, not a surprise found by readers later. If a chapter needs a concept from a later chapter, the graph catches it before any prose is written.

The method is stack-neutral. It works for a printed book with QR linked extras, a static site, a notebook based book such as Jupyter Book, a PreTeXt or Runestone book, or a set of Markdown files. Those systems are examples of places to build, never requirements.

## Workflow

### 1. Fix the frame

Collect before mapping anything:

- Reader: who they are and what they can already do on entry. Name the entry skills as testable statements, not grade levels.
- Terminal performance: one sentence with an observable verb, the conditions given, and the standard that counts as success.
- Scope line: what the book will teach, and what it deliberately will not teach, with reasons.
- Delivery constraints: print, web, or both, whether code can run, whether scripts may be blocked, and how readers get feedback.

If the terminal performance is vague, sharpen it with the requester first. A graph built from a vague goal produces vague nodes.

### 2. Inventory the nodes

List concepts and procedures as nodes before writing any chapter outline. Use the worksheet in `references/learning-graph-worksheet.md`.

- Keep each node small enough to teach in one section and test with one or two items. Split a node when its prerequisites split, or when you cannot write a test item for it as stated.
- Give each node a stable id in lower case with hyphens, a title, a type (concept, procedure, or discrimination between confusable cases), the behavior that shows it was learned, and the common misconception readers bring to it.
- Ground the node format in concept mapping practice: Joseph Novak and his team at Cornell developed concept maps in the 1970s from David Ausubel work on meaningful learning. A map has concepts as nodes and labeled links that form propositions. Borrow that discipline here, then add prerequisites, which concept maps alone do not enforce.

### 3. Draw the prerequisite edges

For each node, list only the nodes a reader must already have in place to learn it well. This is the knowledge space idea: a domain as a set of knowledge items with dependency links, where for example solving linear equations sits before solving quadratic equations because the second builds on the first.

- Write each edge as a proposition with a why line: prerequisite, linking phrase, dependent, plus one line on what breaks without it. Example: signed difference, is needed to compute, percent change, because direction is lost without the sign.
- Drop edges you cannot justify in the why line. Related is not prerequisite. Mentioned earlier is not prerequisite.
- Expect a directed acyclic graph. If two nodes each need the other first, split one into an introductory node and a full node. Cycles are design errors, not reader problems.

### 4. Check the graph and order the chapters

Put the graph in the JSON shape shown in `references/worked-mini-textbook.md` and run the checker:

```
python3 bin/graph_check.py graph.json
python3 bin/graph_check.py graph.json --strict
```

The checker reports duplicate ids, unknown prerequisites, assessments that test nothing, nodes with no assessment coverage, chapter order violations, and cycles. It prints a topological order using Kahn method: repeatedly take nodes with no unmet prerequisites, which runs in time proportional to nodes plus edges and fails when a cycle remains. Plain mode treats unassessed nodes as warnings. Strict mode treats them as errors, and strict is the mode to pass before release.

- Group nodes into chapters from the topological order. A chapter holds nodes that become teachable at about the same point and share a setting or problem type.
- If a draft chapter outline already exists, map it against the graph instead of trusting it. Move nodes that violate the order, or add a short bridge section that teaches only the missing prerequisite.
- Write for each chapter an opening problem posed before any method, the nodes it covers, and a closing task that uses all of its nodes together.

### 5. Write assessments before prose

Follow backward design, from Wiggins and McTighe in Understanding by Design (1998): identify desired results first, determine acceptable evidence second, plan learning experiences third. For a textbook that means items come before chapter text.

- Write at least one item per node, and record which node each item tests. An item that tests no node is cut or rewritten.
- Build distractors from the misconceptions recorded at step 2. Feedback for a wrong answer names the misconception, points to the exact section that teaches the point, and offers one smaller retry problem.
- Add at least one transfer item per chapter: same nodes, new surface story, no numbers or wording copied from the worked examples.
- Keep embedded checkpoints formative. Readers get feedback and a path back into the text. Do not lock later chapters behind a checkpoint score.

### 6. Design each section around a worked example

Write the section prose last, one node at a time, in this order inside each section:

1. Opening problem or question, posed before the method.
2. Short core explanation, with any diagram and its text integrated in one place. Splitting a diagram and its explanation across pages forces readers to hold one while hunting for the other, which wastes working memory.
3. One fully worked example, each step shown with its reason.
4. Faded examples: near copies of the worked example with blanks that grow, following cognitive load research on worked and faded examples. Searching for a strategy while also applying it overloads a beginner. Studying a solved problem first, then completing partial solutions, removes that double load.
5. The checkpoint items for the node, with feedback.
6. A short recap that states the node in one or two sentences and names what it unlocks next in the graph.

### 7. Add interactivity only where it earns its place

Pick patterns from `references/interactive-patterns.md`. The short list:

- Predict, run, explain for simulations and runnable code: the reader writes a prediction before touching anything, runs it, then explains any gap in one sentence.
- Step-through for mechanisms and algorithms: step one move at a time, predict the next state before revealing it.
- Parameter sweep for sensitivity and tradeoffs: vary one input, record outputs in a table, then state the pattern.
- Parsons style reordering when order itself is the learning point: arrange scrambled steps into the one correct order.

Rules for every interactive element:

- Attach a task. Free exploration with no question teaches little and cannot be checked.
- State what the reader should notice, in the task or in the debrief right after.
- Ship a static fallback that teaches the same point: a table of precomputed cases, a printed trace, or an answer key with reasoning. The book must still work in print, as PDF, or with scripts blocked.
- Keep it small. One simulation per node is a ceiling, not a target. If passive text plus a worked example teaches the node, cut the simulation.

Platform notes, as examples only: Runestone books show embedded self-check questions with per answer feedback, code step-through, and Parsons problems inside the text, with reading work scored on interaction rather than correctness. Jupyter Book shows the notebook route: write in Markdown or notebooks, execute code at build time, cache outputs, and insert results inline. Use either if the project already lives there. Use neither if it does not.

### 8. Run the gap audit and revise the graph, not just the prose

Before calling the book done, run all of these:

- Graph checker in strict mode passes: no cycles, no unknown prerequisites, no unassessed nodes, no chapter order violations.
- Every quiz item maps to a node, and every node maps to a section that teaches it.
- Every interactive element has a task, a debrief, and a static fallback.
- Every worked example is followed by at least one faded example or practice item before the next node starts.
- Reader test if possible: give one reader the book cold and log every place they stall. Classify each stall. Missing prerequisite means a missing node or edge, so fix the graph. Confusing wording means fix the section. The classification decides the fix.
- When reader errors cluster on an idea that is not a node, promote it to a node with its own edges, section, and items. Do not patch a missing node with a warning paragraph.

## Output Contract

Deliver these, in this order:

1. The learning graph: worksheet or JSON, with node ids, prerequisites with why lines, and the checker output showing the topological order.
2. The chapter plan: chapters in graph order, each with its nodes, opening problem, and closing task.
3. The assessment map: one row per node with item ids, item kind, and what a wrong answer reveals.
4. The book sections, or for a planning request the section specs, each following the order in step 6.
5. The interactive element plan, with fallbacks.
6. The gap audit result: checker output in strict mode plus the checklist from step 8, with any remaining gaps stated plainly.

A worked end to end example, a mini textbook on percent change with its graph JSON, a finished section, a slider task with fallback, and aligned quiz items, is in `references/worked-mini-textbook.md`. Match its completeness on real projects, scaled to the topic.

## Operating Rules

- Graph before prose, items before sections, always. Reversing that order is the main failure this skill exists to prevent.
- Never invent a prerequisite to make a chapter outline look tidy, and never drop a real prerequisite because it is inconvenient to teach early. The graph describes the subject, not the preferred table of contents.
- Keep claims about learning methods tied to what the sources support. Concept maps, knowledge spaces, backward design, and worked examples have real research behind them. Do not promise score gains, percentages, or timelines for a book built this way.
- Do not tie the book to one vendor, library, or file format unless the requester already uses it. Name a platform only as an example of a pattern, with the pattern stated in plain terms first.
- Treat reader stall data as graph data. Repeated failure at one point is evidence about the book structure first, and about readers last.
- If the topic is too large for one graph a reader can hold in view, split the book into volumes or units, each with its own graph, and state the entry nodes each later unit assumes from earlier ones.