Code as docs

The usual deal is docs as code. You take the weaker artifact, the documentation, and drag it up to the rigor of the code: put it in version control, review it in pull requests, build it in CI, fail the build when a link rots. The whole discipline is about lifting docs to meet the standard the code already holds.

Kiln leans the other way, toward code as docs.

The code is the source of truth. A doc is a view onto it. The feature pages you're reading live in the same repo as the app and render inside Kiln itself (⌘3), so the explanation sits next to the thing it explains and moves when that thing moves. The doc stops being a parallel artifact you have to remember to update. It becomes a projection of the code, kept honest by proximity.

Why this is the better trade

Documentation has two halves. There's the part only a human can write, the why: the mental model, the dead ends you avoided, the reason it works this way and not the obvious other way. And there's the part that's pure bookkeeping, the keeping-it-true: this flag was renamed, that panel moved, the shortcut is ⌘3 now, not ⌘2.

Docs as code makes the bookkeeping cheaper but never free. Someone still writes the update, someone still reviews it, and the doc still drifts the moment attention lapses. Code as docs collapses the bookkeeping half almost entirely. When the doc is a view onto the code, the boring part of staying true mostly takes care of itself, which frees you to spend words only where a human actually needs a human.

The honest caveat

This works because the audience already has the code, the running app, and the context. Inside a small, high-context team, the code can carry most of the explanation, and the few words you add land on top of shared ground.

Point the same idea at strangers and the gaps reopen. The why, the mental model, the shape of the thing, the things the code can't say about itself, become the whole job again, and you're back to writing real documentation. So treat code as docs as a luxury of proximity, not a claim that docs are obsolete. The bookkeeping evaporates. The thinking doesn't.

That's the line these public pages walk. They're a companion to the app, written once and kept true by living next to it, with the human half, the why, written in plain language on top.