"Document later" is how teams say "document never"
We learned this the hard way on a recent project.
The setup: a multi-tenant system where onboarding each new tenant meant repeating a precise 15-step ritual. A config here. A table there. A reconciliation rule. A UI entry. The first time, our lead engineer just knew. The second time, he half-remembered. The third time, an "obvious" step got skipped, a deploy went sideways, and our team spent two hours retracing what should have been a thirty-minute task.
Sound familiar?
The cost of "later"
Every team we've worked on pushes documentation to a separate sprint that never quite happens. Tickets get shipped. PRs get merged. Slack threads decay. The system grows in a way that only its three original authors can still navigate. New hires onboard slowly. Clients ask questions that nobody can answer without paging the senior engineer. The codebase quietly becomes a fortress of tribal knowledge.
The myth is that documentation is expensive to write. The truth is that retro-documentation - sitting down six months later trying to reconstruct decisions from git history - is what's expensive.
What we changed
On this project, we tried something different: documentation lived inside the repo, deployed alongside the application, and got written as part of every feature - not after.
We used VitePress to render a documentation site directly from the same git repository as the code. Push the code on Monday, push the doc update in the same PR, the site rebuilds, the team sees the change in minutes. No separate Confluence space. No parallel wiki to drift out of sync. The docs aged at exactly the same rate as the code.
Three things this unlocked for us:
1. Architecture decisions stopped getting lost.
Every non-obvious decision - why we picked one pattern over another, what alternative we rejected and why - got a short page. Six months later when someone asked "why is it built this way?", the answer was a link, not a meeting.
2. Client expectations became reviewable.
When the client wrote in Slack "make sure new tenants work the same way," we converted that into a written page describing what "the same way" actually meant. The client reviewed it, agreed, and we had a shared definition of done before a single line of code shipped. No more launch-day "wait, I thought it would do X" surprises.
3. Architecture diagrams stopped being throwaway.
Diagrams used to live in Slack screenshots, slide decks, Lucidchart exports - all eventually stale, none authoritative. With everything in one site, the diagram lives next to the prose that explains it, and they age together. If the diagram is wrong, the page is wrong, and someone catches it in code review.
Where AI fits in
The argument against documentation has always been time. AI changed the math for us.
We now draft documentation pages with an LLM in ten minutes that would have taken us an hour. Architecture writeups, runbooks, onboarding playbooks, even the long tenant-onboarding guide - all started as AI-drafted skeletons that we then edited for accuracy and tone.
Here's the part most people miss: AI is great at drafting, not at deciding. The human still owns the decisions. AI doesn't know why our team picked one pattern over another - we do. AI doesn't know what our client cares about - we do. AI takes the draft from blank-page-paralysis to 70% done; the team does the last 30%.
This shifts everything. Documentation used to be a multi-hour tax. Now it's a fifteen-minute task. At that price point, "document later" stops being defensible.
Why this applies to any project
This isn't specific to the domain we were working in, or to the stack we used. It's a pattern:
- A docs site (VitePress works well; pick what fits your team) generated from the same repo as the code
- Architecture decisions written as you make them, not after
- Client expectations captured as written, reviewed artifacts
- Diagrams stored next to the prose, not in separate tools
- AI as the drafting partner, the team as the editor
Whether it's a payments platform, a CRM, an analytics pipeline, or an internal admin tool - the same pattern holds. The cost of documenting has collapsed. The cost of not documenting has not.
The shift
"Document later" used to be a reasonable trade-off when documentation was expensive. It isn't anymore.
Our new rule: a feature isn't done until the doc page is updated. If that sounds like overhead, run the experiment for one sprint. You'll get the hours back from the meetings, the Slack threads, and the bug investigations that good documentation quietly prevents.
What's the documentation gap your team is dragging around right now - the one nobody has time to fix?
