For most of my career, documentation was the last thing I wrote and the first thing I let go stale. It was a chore I performed when onboarding a new hire or when a project changed hands. Between those moments, the source code was the source of truth and the rest was theatre.

That assumption no longer holds. The cost of bad documentation used to be a slow new hire. Today, it is an agent that confidently produces the wrong code at three in the morning.

The setup has changed under us

A year ago, asking Claude Code or any other agent to “implement feature X” assumed I had a person in the room who could correct its premises. The agent could be wrong about the data model, the auth flow, the naming convention, and I would notice in the PR.

The cycle is now compressed. I have agents opening pull requests from a Linear ticket while I’m in a meeting, finishing entire features overnight, refactoring modules in parallel. The agent’s input is no longer “what I just told it five minutes ago”, it is “everything the project knows about itself”. When the project knows the wrong thing, or knows nothing, the agent shrugs and invents.

Documentation went from optional to load-bearing. It is now the working memory the agent runs on, and the contract every human collaborator silently expects to be true.

Two requirements come out of that, and they pull in different directions.

The agent has to be able to read it. Plain text, indexable, addressable, ideally checked into the repo so it travels with the code. The agent does not need a beautiful sidebar, it needs a stable path it can grep.

The team has to be able to live in it. Product, design, ops, the freelance illustrator your client hired last week, none of them will clone the repo. They want to comment, edit, link to a section, leave a draft. They want Notion-shaped affordances, not Markdown PRs.

Most projects pick one of those poles and lose the other. The rest of this post is the landscape I look at when I am trying to keep both.

In-repo Markdown: the agent’s native habitat

The most underrated option is also the simplest: write the docs as .md files in the repo. Co-located with the code, versioned with the code, reviewed in the same PRs as the code.

A few conventions have crystallised this year and are worth knowing by name.

CLAUDE.md is Anthropic’s convention for instructions that Claude Code reads automatically when it opens a project. It is the place where you write down the things you would tell a new contractor on day one: stack, conventions, gotchas, where the bodies are buried.

AGENTS.md is the vendor-neutral version of the same idea, supported across multiple coding agents. If you want one source file that several tools can read, this is it.

llms.txt applies the same idea to your public documentation: a single file at the root of your docs site that points an LLM at the canonical pages, in the order they should be read.

The strength of this approach is brutal: it is free, it sits in version control, and every coding agent already knows how to read it. The weakness is just as brutal: nobody outside engineering will touch a Markdown file in a private repo. The wider team is locked out by default.

For a solo project or a tight engineering team, in-repo Markdown plus CLAUDE.md is often enough. For anything with non-engineers in the loop, it is the foundation, not the whole house.

Doc platforms: Mintlify, Fern, GitBook, ReadMe, Docusaurus

If the project has any external audience (an API, an SDK, a public product), a dedicated documentation platform earns its keep.

Mintlify is the one I reach for most often right now. Docs are written as MDX in a repo, deployed automatically, and the platform builds an AI-native experience on top: site search, an ask-the-docs chatbot, structured metadata for agents. Crucially, the source of truth stays in your repo, which means the same files feed your live docs and your in-repo agent context.

Fern takes a similar repo-first approach with a stronger focus on SDK generation. If your docs are mostly an API reference, Fern often wins on output quality.

GitBook and ReadMe sit closer to the editor-first end. The docs live in their app, with optional Git syncing. The editing experience is friendlier for non-technical contributors, at the cost of being slightly further from the code.

Docusaurus is the open-source workhorse. Less polish out of the box, total control, no vendor lock-in. Worth considering when the docs site is going to outlive the company subscription budget.

All of these are good. The question is rarely “which one is best”, it is “which side of the repo-vs-app spectrum matches who is going to write the docs”.

Wikis: Notion, Confluence, Slab, Outline, Coda

For internal documentation, the picture flips. The audience is the whole team, not the public, and the content is messier: meeting notes, decisions, half-formed specs, onboarding pages, RFCs, post-mortems.

Notion has effectively won this category for new projects. The fact that there is now an official Notion MCP server is, I think, the most important documentation development of the past twelve months. It means a coding agent can finally read the same internal docs the team reads, without me having to mirror every page into a .md file.

Confluence is still the default in larger companies. It is not loved, but the integrations exist and the data is there.

Slab, Outline, and Coda sit in the same shape as Notion, with different opinions about structure, search, and embeds. Outline is the one I point self-hosted teams at.

The MCP angle is the thing to watch here. For any wiki you are evaluating in 2026, the question is no longer just “does the team like the editor”. It is “can my agent read this without me building a bridge”. If the answer is no, the wiki is going to drift further away from the code every week.

The thing nobody is solving yet: keeping it fresh

Picking a tool is the easy part. The hard part, the one I have been chewing on for months, is keeping the documentation accurate as the code moves faster.

A coding agent that ships three PRs a day will outpace any human’s appetite for writing docs. The traditional answer (“the engineer who shipped the change updates the docs in the same PR”) falls apart when the engineer is also an agent and the human is reviewing diffs, not writing them.

The pattern I am converging on is to treat documentation as an agent task, not a human task. After a feature lands, an agent re-reads the diff, walks through the docs, and proposes updates as a follow-up PR. The human reviewer approves the doc PR the same way they approved the code PR. The doc agent does not need to be clever, it needs to be relentless.

flowchart LR
    A[Code PR<br/>merged] --> B[Doc agent<br/>reads diff]
    B --> C[Walks docs<br/>flags drift]
    C -->|finds drift| D[Opens<br/>doc PR]
    C -->|no drift| E[Done]
    D --> F[Human<br/>reviews + merges]

This is the missing piece of every doc stack I have used so far. Mintlify can render anything I push, but it cannot tell me my CSV export now takes a format parameter. Notion can host the spec, but it cannot detect that the spec is now lying. An agent loop that closes that gap is, in my current view, the single biggest unlock available to a small team this year.

My current default stack

For a typical project I start today:

  • CLAUDE.md and AGENTS.md at the repo root, hand-written, treated as the agent’s onboarding doc.
  • An in-repo docs/ folder of Markdown for everything technical and durable (architecture, schemas, runbooks).
  • A Notion workspace for everything mushy and collaborative (specs, meeting notes, decisions), connected through the Notion MCP so the same agent can read it.
  • Mintlify on top of docs/ when there is anything external-facing to publish.
  • A doc-update agent that runs after each merged PR and opens a follow-up PR if it thinks the docs drifted.

It is not the cheapest stack, and it is not the most elegant. It is the one that has stopped me waking up to an agent confidently producing the wrong feature.

The thing I keep telling clients is that in 2026, your documentation is no longer a deliverable. It is a system. It has inputs, outputs, and a refresh cadence. The teams that figure this out first will ship faster than the ones still treating docs as a chore.

The agents are ready to read. The question is whether the docs are ready to be read.