4 posts
Literate programming keeps documentation, tests, and implementation in sync by making a Markdown file the single source of truth.
Your docs, tests, and code are three files telling the same story badly. You update the function signature in the source. You forget the README example. A week…
LLM conversations contain intent, rejected alternatives, and working code. That's exactly what documentation should be.
You spent forty-five minutes with Claude designing a retry circuit. You explained the failure modes, rejected exponential backoff because it hides cascading…
Literate programming promised that code should be written for humans first and machines second. Four decades later, almost nobody writes that way.
In 1984, Donald Knuth published a paper that proposed a radical inversion. Programs should not be written for compilers and annotated for humans. They should…
Architecture documentation rots the moment you save it. Here's how to keep docs honest using code-generated diagrams, ADRs, and automated architecture tests.
Every architecture diagram I've seen in a wiki was wrong. Not dramatically wrong. Just quietly, incrementally wrong. The service labeled "Auth" was split into…