This repository is a small experiment exploring how literate programming ideas can be adapted to modern JavaScript/TypeScript workflows, especially in the era of coding agents and conversational programming.
The goal of this project is not the functionality itself—printing today’s date—but the structure: code as a narrative, with human-oriented explanation taking priority over raw implementation.
Our discussion began with Donald Knuth’s concept of literate programming, where the author writes programs as if they were essays—prioritizing explanation, intention, and conceptual clarity. In Knuth’s world, the code is secondary, embedded within a larger textual story.
We then connected this to modern realities:
- Developers increasingly communicate intent to AI coding agents in natural language, not code.
- The text (requirements, reasoning, constraints) often matters more than the code produced.
- Yet the output from agents is usually just raw code with sparse structuring.
This creates a gap:
Your thought process gets lost on the way to the final implementation.
Literate programming offers a useful mental model for closing that gap.
This project demonstrates a minimal modern version of the literate approach using JavaScript.
- Treat the file like a chapter, not just a script.
- Embed WHAT, WHY, and HOW directly into the narrative.
- Let the code be a small, almost incidental fragment at the end of each conceptual unit.
- Make the file readable even to someone who barely writes code.
This aligns with a broader vision we explored:
- High-level textual interaction with coding agents.
- Code existing as a projection of a more important human-readable layer.
- Potential future architectures where:
- each microservice has a “book page,”
- most of the logic is described textually,
- and agents maintain the synchronized code beneath.
A fully literate-style example:
- Starts with narrative.
- Organizes intent using WHAT / WHY / HOW blocks.
- Contains only a tiny amount of actual code.
- Prints the current date in
YYYY-MM-DDformat.
Simple project metadata and a start script.
npm install
npm run start