Narrative Programming: Code Stories as Configuration

Published: September 12, 2025

The Problem with Code Stories

We've all been there. You inherit a codebase, and the person who wrote it is long gone. The code works, but why does it work? What was the author thinking? What's the story behind these architectural decisions?

Traditional documentation gets stale. Comments get out of sync. And nobody has time to write comprehensive guides that actually help people understand the narrative of the code.

But what if telling stories about code was as simple as writing a configuration file?

Reducing Storytelling to Primitives

After building systems for code exploration and documentation, I realized that all code storytelling boils down to three fundamental operations:

  1. Load code (set the stage)
  2. Navigate and highlight (direct attention)
  3. Comment with attribution (provide narrative voice)

That's it. Every code walkthrough, every explanation, every "here's how this works" session uses just these three primitives.

The Narrative Programming Approach

What if we could write stories about code using simple YAML configuration embedded in human-readable Markdown? Something like this:

- action: find_and_highlight
  target: "function calculateTax"
  color: "blue"
- action: display_comment
  text: "This is where the magic happens - we calculate tax based on the user's location"
  author: "Sarah"
  color: "green"
- action: find_and_highlight
  target: "tax_rates[location]"
  color: "yellow"
- action: display_comment
  text: "Notice how we look up rates dynamically rather than hardcoding them"
  author: "Mike"
  color: "blue"

The Power of Declarative Stories

This approach creates democratized code storytelling. Anyone can write narrative flows because it's just configuration, not custom tooling. The stories become shareable artifacts that travel with the code.

But here's the really interesting part: when you combine this with version control, you get temporal storytelling. Stories can evolve with the codebase, break when code changes, and remain historically accessible at the exact commit where they were valid.

Here's what you can actually do with advanced narrative programming:

Interactive Flow Control

Stories become interactive experiences with branching narratives:

- action: marker
  label: "start_walkthrough"

- action: yes_no_question
  question: "Do you want to see the incident handling workflow?"
  yes_marker: "incident_workflow"
  no_marker: "skip_to_code"

- action: marker
  label: "incident_workflow"
  # Incident workflow content here

- action: yes_no_question
  question: "Would you like to restart the walkthrough from the beginning?"
  yes_marker: "start_walkthrough"
  no_marker: "end_walkthrough"

Temporal Incident Replay

Package walkthrough scripts with the code version they demonstrate, including before/after comparisons:

- action: git_checkout
  commit: "HEAD~1"
  file: "src/incident_handler.py"
  title: "Before Fix (HEAD~1)"

- action: display_comment
  text: "BEFORE: Notice the missing error handling that caused the incident."
  author: "Post-Incident Analysis"
  color: "orange"

- action: git_checkout
  commit: "HEAD"
  file: "src/incident_handler.py"
  title: "After Fix (HEAD)"

- action: display_comment
  text: "AFTER: Added proper error handling and logging."
  author: "Fix Author"
  color: "green"

Multi-File Guided Tours

Load README files with interactive walkthroughs, just like those new app tutorials that walk you around the screen:

- action: load_file
  file: "README.md"
  title: "Project Overview"

- action: sleep
  duration: 2000

- action: find_and_highlight
  target: "## Quick Start"
  color: "green"

- action: display_comment
  text: "Let's start with the quick start guide. This shows how to get the system running locally."
  author: "Guide"
  color: "green"

Fix stories when they break (if you care about them), delete obsolete stories knowing they'll still exist in Git history, and create living documentation that time-travels.

Universal API Philosophy

This is how I build everything. Every system I create has multiple interfaces - CLI commands, Python modules, web interfaces, YAML workflows - all using identical navigate/highlight/comment functions under the hood. The same underlying API powers everything.

Multi-Interface Design

Whether you're using:

  • CLI commands for scripting and automation
  • Python modules for programmatic control
  • Web interfaces for interactive exploration
  • YAML workflows for declarative storytelling

...they all use the same core functions. Learning one interface teaches you all interfaces. Skills transfer seamlessly between contexts. Community knowledge compounds across all tools.

LLM Control and CLI Scripting

The same API that powers narrative storytelling also enables LLM control of viewports. You can script interactions from the CLI, putting your own files up without burning tokens. Since you can script it yourself, you can use it to tell stories.

Stories as State Transitions

A story is just a packet of information and a series of changes that takes it from one state to another. That's what narrative computing is - and that's how the whole system has been designed. The same API that lets you highlight code and add comments also lets you:

  • Load files and navigate their structure
  • Checkout git commits for temporal comparison
  • Create branching interactive experiences
  • Replay incidents with full historical context

This unified approach means any client can be built on top of the API and achieve the same effects, consumed in any way you want.

You can use it to tell stories - and so can they. That's how the whole system has been designed and built.

What Narrative Programming Enables

With narrative programming, you can build these specific scenarios:

Interactive Code Onboarding

Imagine a new developer joining your team. Instead of handing them a 50-page wiki, they load your narrative script:

- action: load_file
  file: "README.md"
  title: "Welcome to Our System"

- action: find_and_highlight
  target: "## Architecture Overview"
  color: "blue"

- action: display_comment
  text: "Our system uses a microservices architecture with event-driven communication"
  author: "Tech Lead"
  color: "blue"

- action: yes_no_question
  question: "Are you a backend or frontend developer?"
  yes_marker: "backend_tour"
  no_marker: "frontend_tour"

The experience branches based on their role, walking them through relevant code sections with contextual explanations.

Incident Investigation and Replay

When production goes down, instead of digging through logs and git history manually, you load the incident replay script that automatically:

  • Checks out the exact git commit where the incident occurred
  • Highlights the problematic code with annotations from the investigation
  • Shows the fix side-by-side with the broken version
  • Walks through the investigation timeline with timestamps
- action: git_checkout
  commit: "a1b2c3d"  # The commit where incident occurred
  file: "src/payment_processor.py"

- action: find_and_highlight
  target: "def process_payment"
  color: "red"

- action: display_comment
  text: "INCIDENT: Race condition in payment processing caused double charges"
  author: "Incident Commander"
  color: "red"

Code Review Walkthroughs

Pull request reviews become interactive experiences where reviewers can follow along with the author's thought process:

  • Load the changed files with syntax highlighting
  • See the author's comments on why changes were made
  • Navigate to related code that was affected
  • View test cases that validate the changes

Living Documentation

Your README files become interactive tours that update automatically when code changes. No more stale documentation - the walkthrough scripts break when the code they're describing changes, forcing you to keep them current.

The Bigger Picture

This isn't just about documentation. It's about creating infrastructure for collective code understanding where expertise becomes transferable narrative.

When stories are configuration files, they become:

  • Version-controlled alongside the code they describe
  • Collaboratively maintainable by the entire team
  • Machine-readable for automation and tooling
  • Human-readable for direct editing and understanding

What This Enables

With narrative programming, you can build:

  • Interactive code museums where anyone can create guided tours
  • Collaborative learning platforms with real-time commenting during walkthroughs
  • Incident replay systems that show exactly what went wrong, with before/after code comparisons and investigation walkthroughs
  • Onboarding experiences that guide new team members through complex codebases with branching paths based on their role
  • Post-incident reports that replay the entire incident timeline with code changes and context
  • Code review walkthroughs that highlight important decisions and show alternative approaches

Advanced Incident Analysis

Take an incident from your temporal logging system, package it as a replay script, and attach it to your repository. When loaded, it shows:

  • The investigation process before and after
  • Code changes with git commit checkout
  • Side-by-side before/after views
  • Every incident that ever touched the code can be replayed with full context

The key insight is that code storytelling, at its core, is just configuration of attention and narrative. Once you realize that, you can build systems that make expertise shareable and understanding transferable.

The Future of Code Understanding

What if every complex piece of code came with stories? What if understanding legacy systems was as simple as loading up a narrative walkthrough? What if expertise could be packaged and shared as easily as copying a YAML file?

That's the promise of narrative programming: turning code understanding from an art into a shareable, collaborative science.

The best code doesn't just work—it tells a story. And now, telling that story can be as simple as writing configuration.

Want to discuss narrative programming or share your own approaches to code storytelling? I'd love to hear about it.