The spec was forty-seven pages. It had a cover page, a table of contents, and a section on "future scalability considerations" that nobody had asked for. The developer who wrote it was proud. The engineer who inherited it was lost. The client who paid for it never opened it.
This is the documentation trap. Teams either write too much, too early, or they write nothing and hope telepathy carries them through handoff. Both paths end in the same place: a 10 PM Slack message asking how to restart the job queue, followed by someone digging through Git history to find the answer.
Minimum viable documentation software isn't about skipping docs. It's about writing the right docs, at the right time, in formats people will actually use. The five documents that matter are a README, a runbook, a sketch, a data map, and a decision log. Everything else is optional until it isn't.
The Documentation Trap
Most documentation fails for the same reason most software fails: it was built for an imaginary user. The author pictured a careful reader, settling in with coffee and reading every word. The actual user is a stressed developer at 9 PM who needs one command to fix a broken deploy. They're not reading. They're scanning.
The forty-page spec is the classic trap. Written before a single line of code, it describes a system that doesn't exist yet. By week three, the build has diverged from the spec. By week six, the spec is fiction. By month three, nobody trusts it enough to update it, so it sits in SharePoint like a digital fossil.
Another trap is the wiki. Wikis feel virtuous. They're collaborative, searchable, and organized. They're also where documentation goes to die. The page last edited in March still claims the API runs on port 3000. It moved to 8080 in April. Nobody updated the wiki because updating wikis isn't anyone's job. It just feels like it should be.
Fast builds need living documents. Documents that decay visibly when they're wrong. Documents that are so close to the code that updating them is easier than explaining why you didn't.
The Five Docs That Matter
You don't need a style guide. You don't need a glossary. You need five things, and you need them in this order of priority.
README. One page. How to run the thing locally. What environment variables matter. The one command that starts the dev server. If a new engineer can't clone and run in fifteen minutes, the README isn't done. It lives in the repo root, not in Confluence, because proximity to code is the only thing that guarantees it gets updated.
Runbook. What breaks and how to fix it. Not a theoretical guide to the architecture. A practical list of failure modes and recovery steps. The database connection drops — what do you check first? The scheduled job didn't run . where's the log? The runbook is the document you open at 2 AM when something is on fire. It should read like a checklist, not an essay.
Sketch. A napkin-level architecture diagram. Boxes and arrows showing what talks to what. It can be a photo of an actual napkin. It can be a screenshot from Excalidraw. The point isn't polish. The point is giving someone a map before they get lost in the code.
Data map. Where things live. Which database has customer records. Which table stores the audit trail. Which S3 bucket holds the exports. When you're debugging, half the battle is finding the right data source. A data map cuts that time from twenty minutes to twenty seconds.
Decision log. Why you chose X over Y. Not every decision, just the ones that cost you sleep. Why Postgres instead of Mongo. Why you picked Stripe over Paddle. Why the auth flow is custom instead of off-the-shelf. Six months later, when someone asks "why didn't we just use...", the decision log saves you from relitigating arguments you've already had.
Who Writes What, and When
The FDE writes the first draft of all five documents during the build. Not after. During. Documentation written two weeks after shipping is documentation that never gets written. The context is fresh, the pain is recent, and the engineer still remembers why they made that weird choice in the config file.
Clients own the runbook after week two. This is the handoff moment. The FDE seeds the document with the known failure modes. The client adds the business-specific ones — the vendor who always sends bad data on Fridays, the report that needs to run before the morning standup, the person who should be called if the pipeline breaks on a holiday.
This division matters because operational context lives with the client. The FDE knows how the system works. The client knows how the business works. The runbook needs both. In compressed timelines, like a one-week prototype sprint, this handoff rhythm becomes even more critical.
For teams following a rapid prototyping playbook, this rhythm is essential. You can't ship fast if you're still writing docs two weeks later. The documentation is part of the build, not a separate project. And when you're ready for structured handoff, these five documents become the checklist that proves the system is truly transferable.
Format Over Formality
A shared Google Doc beats a wiki because people actually edit Google Docs. A screenshot of the admin panel with arrows drawn on it beats a paragraph describing the UI. A two-minute Loom video beats both because it shows the thing happening in real time, complete with the pauses and hesitations that reveal how something actually works.
The best documentation I've seen for a data pipeline was a single Slack thread. The engineer had pasted the cron expression, the log location, and the three commands to check if it was healthy. It wasn't pretty. It was useful. Six months later, that thread was still pinned and still correct.
Don't confuse completeness with usefulness. A document that covers every edge case but nobody reads is worse than a half-finished doc that saves someone twenty minutes every week. Optimize for retrieval, not for comprehensiveness.
The Handoff Test
Here's the standard: can someone new deploy this on a bad Monday morning? Not a good Monday. A bad one. The kind where the alarm didn't go off, the coffee machine is broken, and the client's CEO is asking why the numbers look weird.
If that person can find the README, start the system, check the runbook for common failures, and verify the data using the data map — without calling you . then your docs are good enough. If they have to Slack you, you have a documentation gap. Fix the gap, not the whole wiki.
Prototypes that graduate to permanent infrastructure live or die by this test. Many FDE builds start as experiments and graduate to infrastructure. The teams that survive this transition are the ones who wrote the five docs while they were still in prototype mode. The teams that struggle are the ones who said "we'll document it later." Later never comes.
If you're building with speed in mind, pair your docs with a solid testing strategy for rapid prototypes. Tests and docs are siblings. One tells you what the system should do. The other tells you how to fix it when it doesn't.
Documentation Debt
Like technical debt, documentation debt accumulates quietly. A README that mentions a deprecated command. A data map that references a table you dropped in sprint three. A decision log that stops at month two because the team got busy. These little lies compound until someone makes a bad decision based on outdated information. The teams that avoid this trap treat docs as part of the build, not an afterthought — a habit we covered in our FDE onboarding guide.
The fix is small, frequent updates. Treat documentation like code reviews. Every pull request that changes behavior should update the relevant doc. Not the whole wiki — just the one paragraph that matters. Five minutes of doc maintenance per PR saves hours of confusion later.
But beware the opposite trap: over-documentation. I've seen teams spend more time maintaining their docs than their product. If a document hasn't been opened in three months, consider deleting it. If a section takes more than two minutes to read, consider cutting it. The goal isn't a library. It's a flashlight.
Your documentation is done when a stranger can run the system without calling you. Before that, you're not documenting — you're hoarding context. And context hoarding doesn't scale.