Markdown is, for most writing tasks that a developer encounters, the right tool. It is small, it is familiar, and its delimiters have become a kind of lingua franca for prose that wants a little structure without the ceremony of HTML. But Markdown, for all its virtues, has no opinion about the internal morphology of a German strong verb. When I set out to build Konjugieren, a free iOS app for learning German conjugation, I discovered that the one thing I most wanted to show my readers was the one thing Markdown could not convey.

Continue reading →

Not all documentation serves the same purpose. A style guide tells you what to do on every page. A glossary tells you what a word means when you encounter it. A phone directory tells you how to reach someone when you need her. These are different instruments, and combining them into a single document does not produce a style guide that is also a glossary and a phone directory. It produces a document that is too long to scan and too broad to maintain. I recently learned this lesson in a context I had not anticipated: the Markdown file that governs my AI co-developer’s behavior.

Continue reading →

Reviewing your own code is hard. Not because you lack the skill, but because you lack the distance. You wrote the code; you know what it is supposed to do; and that knowledge of intent inoculates you against noticing what the code actually does in its edge cases, its error paths, and its quiet inconsistencies. I recently asked Claude Code to perform a comprehensive code review of Konjugieren, my German verb-conjugation app, and the results were instructive: not for the showstopping defects it found (there were none), but for the characteristic distribution of what it did find. Sixteen issues across three severity tiers. I fixed eleven, declined two with explanation, and learned something about the complementary strengths of human judgment and AI exhaustiveness.

Continue reading →