The best lesson I have had on documentation did not come from a guide. It came from opening a codebase somebody else wrote, with no README, no notes, and no map. It ran, in theory, but I could not tell how to start it, why it was built the way it was, or what would break if I touched the wrong thing. Every hour I spent guessing was an hour a single page of writing would have given back.
So I went looking for what a project is actually supposed to have. Two surprises came out of it. First, “documentation” is not one big chore, it is a handful of small documents, each answering one specific question. Second, you do not write them all at once. The set grows as the project grows, from a solo experiment to something a team depends on, and knowing which stage you are at tells you exactly what to write next.
Each document answers one question
The trap is thinking of docs as a wall of text you owe the project. They are not. Each type exists to answer a different question a future person will ask, and that person is usually you in three months, with no memory of today.
Three of them get confused constantly, so here they are pinned to their question:
| Document | Answers | Example |
|---|---|---|
| README | How do I use this now? | ”Run npm install, then npm run dev.” |
| CHANGELOG | What changed, and when? | “v2.1 removed the old login.” |
| ADR | Why was it built this way? | ”We chose Postgres over Mongo because…” |
An ADR, or Architecture Decision Record, is a short note capturing one important decision: what the situation was, what options existed, what you picked, and what it costs you. It is the document I missed most in that raw codebase, because the code shows you what is there but never why.
NOTE
The “why” is the part that evaporates. Six months on, nobody remembers why the database was chosen or why a weird workaround exists, and without an ADR that reasoning is gone for good. The code cannot tell you, it only shows the result.
Documentation grows up with the project
You do not need all of it on day one. The clearest way I found to think about this is a maturity ladder, adapted from an open-source “README maturity model”: documentation climbs from nothing to product-grade as more people depend on it. Match your rung to who actually reads your project.
flowchart TD L1[Solo / experiment<br/>README + how to run it] --> L2[Small team<br/>+ architecture overview, ADRs, CHANGELOG] L2 --> L3[Professional / at scale<br/>+ organized doc set, docs-as-code, API reference]
| Stage | Who reads it | What it needs |
|---|---|---|
| Solo | You, later | README + setup steps. Just do not leave it blank. |
| Small team | A few teammates | Add an architecture overview, ADRs for real decisions, a CHANGELOG, and a short “how to contribute”. |
| Professional | Many people, maybe outside users | A deliberately organized doc set, kept next to the code, plus full API reference and a light process for big changes. |
TIP
The mistake goes both ways. A solo project buried under enterprise-grade docs never gets finished. A team project with a solo-level README bleeds hours onto everyone who joins. Write for the rung you are on, and climb when a real person is blocked.
The lower rungs are also the cheap ones. Going from a blank folder to a decent README is an hour that pays back on the first person who opens the project, you included.
The professional trick: organize by what the reader wants
At the top of that ladder, professional teams stop piling everything into one file and start sorting docs by what the reader is trying to do. The most popular way to do this is a framework called Diátaxis, which splits documentation into four kinds:
| Type | The reader wants to… | Feels like |
|---|---|---|
| Tutorial | learn, get a first win | a guided lesson |
| How-to guide | get one task done | a recipe |
| Reference | look up an exact fact | a dictionary |
| Explanation | understand the why | a conversation |
The insight is that mixing these is what makes docs frustrating. Someone hunting for one exact command does not want a story, and someone learning does not want a raw list of every option. Keeping the four apart is most of what separates docs that help from docs that annoy. You do not need all four early, but knowing the split stops you writing one document that tries to be everything and helps nobody.
Going deeper: docs-as-code, and why AI cares about structure
Two professional habits worth knowing early. Docs-as-code means writing docs as plain text files that live next to the code, in the same version control, reviewed the same way. For a small team, keeping docs close to the code beats a separate wiki that quietly rots.
The other reason structure matters now: AI assistants read your documentation constantly, pulling fragments into their context to answer questions about the project. Well-separated, clearly-labelled docs give the assistant clean pieces to work with, so the same structure that helps a human also makes the AI’s answers better. Messy docs mislead both.
Where to start when the folder is empty
If a document’s only job is to let another person, or the AI helping them, pick up your project without you in the room, three earn their place before anything else.
IMPORTANT
Write these three first, whatever stage you are at:
- README so someone knows what the project is and how to use it.
- Setup docs so they can run it locally without a guessing game.
- Architecture overview, one diagram and a few paragraphs, so they see how the parts connect before diving into files.
These are exactly the three that raw codebase was missing, and exactly the three that cost me a day.
Everything above that is an upgrade you add when the project earns it: ADRs once you are making decisions worth remembering, a Diátaxis structure once the docs outgrow one file, a CHANGELOG once other people track your versions.
Documentation is maintenance, not paperwork
Here is what actually shifted for me. I used to file documentation under “nice to have, if there is time”. After that codebase, I see it as part of maintenance, the same as tests or backups. Code tells the machine what to do. Documentation tells the next human why, and the next human is almost always you, having forgotten. Skipping it does not save work, it just moves the work onto whoever opens the project next.
Write for the rung you are on, and write the document that answers the question someone will actually ask.
Sources
- README maturity model (Opensource.com) for the solo-to-product progression
- Diátaxis documentation framework for the four reader-driven doc types
- ADR vs README vs CHANGELOG for the one-question-each distinction
- Documentation processes and types (Trendyol Tech) for the lifecycle view
- What is docs-as-code (Kong) for keeping docs next to the code