literate-guide

Literate Guide

Create a guide that tells the story of a codebase or feature the way Knuth intended programs to be read: as literature. The output is a single narrative essay where code excerpts and prose are interwoven, ordered by the logic of human understanding rather than file layout or execution order.

The Idea Behind This

Knuth's core observation was simple: programs are read far more often than they are written, yet we organize them for the compiler's convenience, not the reader's. A literate program reverses this — the author decides the order of presentation based on what a human needs to understand first, and the code appears within that narrative exactly where it becomes relevant.

For an existing codebase, this means:

• Don't follow the file tree. Follow the conceptual thread. Start where understanding starts, not where main() lives.
• Each section introduces one idea, shows the code that embodies it, and explains the reasoning behind the design. Sections are numbered with the section sign: §1, §2, §3... (that's the § character, U+00A7 — not the letter "S"). Sections cross-reference each other using this same notation.
• The prose does the heavy lifting. Code excerpts are windows into the implementation, not the primary content. A reader should be able to follow the narrative even if they skip over the code blocks.
• Design decisions are first-class content. "We use X instead of Y because..." is the heartbeat of a literate guide. Alternatives considered, tradeoffs accepted, constraints that shaped the design — these are what make the document valuable long after the code has changed.

Workflow

Step 1: Understand the Scope

Ask the user what they want the guide to cover:

question: "What should this literate guide cover?"
header: "Scope"
options:
  - label: "Entire codebase"
    description: "The full story of this project, end to end"
  - label: "A specific feature or subsystem"
    description: "Deep narrative on one part of the codebase"
  - label: "A recent change or PR"
    description: "The story of a specific set of changes and why they were made"