Writing Documentation That Lives Next to the Code

Most teams agree that documentation matters, and most teams struggle to keep it useful. Documents live in a wiki nobody updates, in chat threads nobody can find or in one person's head. When the code changes, the documentation does not, and soon nobody trusts it.

We keep our documentation inside each project, next to the code, organized in a consistent structure. That way, the same change that updates the code can update the docs, reviewers can see both together and anyone working on the project knows where to look.

A consistent folder structure

Every project uses the same top-level documentation folders, each with a clear purpose:

• Start here: what the project is, how to get oriented and where to go next
• Product: plans, roadmaps and descriptions of what the product should do
• Architecture: how the system is built, its standards and its key decisions
• Operations: runbooks, deployment notes and how to handle common situations
• Reference: lookups, inventories and technical details people need occasionally
• Active work: handoffs and notes for work currently in progress
• Archive: finished or superseded documents kept for history

Because every project shares the structure, moving between projects is easier. A runbook is always in operations. A handoff is always in active work.

Instructions for every contributor

Each project also has a short instructions file at its root that summarizes the most important rules: how to deploy, which modules exist, which standards apply and which actions need approval. It is written for both people and AI assistants. When an assistant starts working on a project, it reads those instructions first, and so does a new teammate.

Active work moves to the archive

Documents about work in progress are useful while the work is happening and can mislead later if they look current. So when a piece of work is finished and accepted, its handoff moves from active work to the archive. The archive keeps history accurate without cluttering the present. You can read about what a handoff contains in handoff notes.

Indexes that point the way

Each documentation folder has an index that lists what is inside and what each document is for. When a document is added, moved or archived, the index is updated and any links that pointed to the old location are repaired. Broken links in documentation are treated like broken links on a website: something to fix, not something to live with.

Dated decisions

Many of our documents record decisions, such as a rule about payments or a change in how a module behaves. Those entries carry dates and, where relevant, who made the decision. A dated decision can be weighed against later changes; an undated one leaves readers guessing whether it still applies.

Documentation changes with the code

When a change affects how something works, the documentation update is part of the same change. A new setting gets described in the operations notes. A new rule gets added to the standards. A new capability gets a help article for customers, reviewed before it is published. Reviewers check that the documentation matches the code, just as they check the code itself.

Write for the reader who arrives cold

Most documentation is read by someone who has just arrived: a new teammate, an assistant starting a fresh session or a future version of the author who has forgotten the details. We try to write for that reader. Documents start with what they are for and what the reader needs to know first. They define unusual terms. They link to related documents rather than assuming the reader has seen them.

A useful test is to hand a document to someone unfamiliar with the work and watch where they get stuck. Each sticking point is a sentence that needs writing.

Keep it honest and current

A document that describes how something used to work is worse than no document, because it is believed. When code changes make part of a document untrue, that part is corrected or clearly marked as historical. Old decisions are not deleted, because the history is valuable, but they are labeled with dates so readers can see what came later.

Customer documentation is separate, but connected

Internal documentation and customer help serve different readers. Internal docs can mention architecture, internal names and plans. Customer help describes what the product does in plain language, without internal labels, as explained in why customers never see our internal phase numbers. Both are updated when a feature changes, but they are written for different people.

Frequently asked questions

Where should software documentation live?

Keeping documentation in the project repository, next to the code, makes it easier to update together and to review alongside code changes.

How do you keep documentation from going stale?

Update documentation in the same change as the code, archive finished work and keep indexes current so readers can trust what they find.

Should AI assistants read project documentation?

Yes. Short instructions files and clear docs help assistants follow the same rules and patterns as the rest of the team.