Text-First: If It Can Be Text, It Should Be Text

Author here. My first blog post after more than thirteen years, but I had to talk about something that matters to me. "Coding is solved"? We'll see. But if anything is close to solved, it's documentation. AI has been better than us at docs basically from day one. Which is fine with me - nobody likes writing documentation anyway. On the other hand, we're all happy when it's there and well-maintained. Documentation has finally become affordable.

I'm surprised by how many people in my workshops still complain about wildly varying results with today's models. In my experience that's almost always a context problem, not a model problem. The post argues for keeping that context as plain Markdown in the repo, so it also serves as documentation for humans. This is Spec-Driven Development, but with the tools you already have. I'm wary of existing SDD frameworks: they often feel a bit too heavy for my taste. Since things are evolving at breakneck speed, I also would like to avoid any kind of abstraction lock-in.

Feel free to try it out yourself. A simple demo with the full run: https://github.com/emboss/text-first-demo (start from the bare-repo branch, compare with the implementation branch, which shows one sample run). I'd be especially interested in where this breaks down for you in brownfield codebases.