Documentation is no longer just for humans. Once you’re building with AI in the loop, the quality of your written context becomes a direct input into the quality of the code you get back.
That changes what documentation is for. It’s not just “so future me understands this”, it’s “so future me and a model can keep building this without re-deriving everything from scratch”.
The Problem
Traditional docs tend to fail in predictable ways:
- Scattered
- Outdated
- Hard to navigate
Most teams know this, but the cost of fixing it always loses to shipping. In a normal workflow, that’s annoying. In an AI-assisted workflow, it becomes expensive because you end up paying the context cost repeatedly.
Documentation as a System
I treat documentation as a system, not a folder. For me, that system lives in Obsidian because it’s local-first, flexible, and built for linking. I’m not trying to build a corporate knowledge base. I’m trying to build a vault that acts like infrastructure.
In practice, that means the vault contains the things I used to keep in my head:
- Specs
- Architecture
- Prompts
- Rules
It also contains the boring glue that makes projects survivable:
- Naming conventions and boundaries (“what belongs where”)
- Design system decisions (DesignKit tokens and components)
- “How I work” workflows (exploration vs execution, verification gates)
- Release checklists and definition-of-done criteria
Making Docs AI-Friendly
AI-friendly documentation isn’t about writing for a model instead of a human. It’s about writing in a way that survives copy/paste into a prompt without turning into ambiguity soup.
The basics matter:
- Clear structure (predictable headings, short sections, no “mystery meat” pages)
- Consistent language (don’t call the same thing three different names)
- Linked content (specs link to architecture, architecture links to rules, rules link to prompts)
- Markdown-first (easy to diff, easy to reuse, easy to feed into tools)
I also keep prompts as first-class artefacts. If a prompt reliably produces good work, it belongs in the vault, alongside the rules that make it work. That’s how you get from “AI helped today” to “AI is part of the system”.
What This Buys You
Good documentation reduces repetition and drift.
- It reduces context rebuild. You’re not re-explaining architecture from memory every time you start a new change.
- It enables reuse. Specs, prompts, and standards become composable building blocks.
- It speeds up onboarding, including your own. If you come back to a project after a month, you don’t have to reload everything from scratch.
There’s also a subtle benefit: writing constraints down forces you to notice where you’re hand-waving. That alone improves design quality, even before any model gets involved.
Obsidian as the Hub
Obsidian works for me because it’s not trying to be a project manager. It’s a graph of knowledge that I can shape around how I actually build.
Local-first matters here as well. I want this to work on a plane, on a train, and in the boring moments between everything else, without depending on yet another cloud service. The end result is that the vault becomes a memory layer for both me and the tools I’m using, and the projects get steadier as they grow.