Engineering documentation

Your team already
decided this.

Twice a quarter somebody reopens a question that was settled in a pull request eight months ago, because the reasoning was in a review thread and the person who wrote it has left. Clearly writes the decision down while the context is still warm, and answers when the question comes back.

Try it free — no signupADR vs wiki ⟶
The gap

Every documentation tool describes what. Almost none keep why.

This is the distinction that decides whether a tool is worth adding, and it is worth being precise about because most comparisons blur it.

Code documentation

Explains how the system works and tracks the code as it changes. Genuinely useful, and it answers a different question — a new engineer can read it and still not know why the retry is exponential rather than fixed.

Published docs

Written for people outside the team — APIs, guides, reference. Deliberately hides the internal argument, which is exactly the part your own engineers need and the part that gets lost.

Decision records

What was chosen, what was rejected, and who argued which way. The knowledge that walks out of the building when a person does — and the only kind that stops a team re-litigating a settled question.

How it works

Three steps, one command

The work already happened across commits, a review argument and an incident channel. Nothing here asks anybody to fill in a template.

Step
01

It reads the work

One pass across the commits, pull requests, issues and channels you connect — diffs and discussion, not your whole Slack. Every source is one you named and can revoke.

Step
02

It writes the decision

What was chosen, the reasoning, the options turned down and who argued against them. Each claim links back to the commit or message it came from, and anything unsourced is left blank rather than guessed.

Step
03

It files and links the note

Markdown in your repo, with a stable filename, linked to every note it touches. The archive gets denser rather than longer, so the tenth note makes the first nine easier to find.

Side by side

Where a decision record earns its place

Two of these rows favour a wiki, and they are real. A hand-written page can carry judgement and long-form argument that nothing automated will match.

What you needWiki pageWritten decision record
Exists without anyone remembering to write it—✓
Records the option you rejected—✓
Names who argued the other way—✓
Every claim traceable to a commit or message—✓
Lives in the repo, versioned with the code—✓
Readable by your coding agent—✓
Long-form architecture narrative✓—
Non-engineers can edit it comfortably✓—

The honest split is that both belong. Keep the wiki for the narrative a person should sit down and write. Let the decision record carry the hundred small, expensive choices nobody will ever schedule an hour for.

What you keep

Nothing here is a place you have to migrate to

Notes are files in your repo

Plain markdown, committed with your code. No database, no export, no migration if you stop. Remove the tool and the archive is untouched — you had the only copy that mattered the whole time.

It never writes code

Read access to the work you point it at, write access to one documentation directory. It cannot open a pull request, push a branch or touch a file outside the folder you name.

Sources stay yours

It reads only what you connect, and every connection can be revoked. It reads diffs and the discussion around them — not an entire workspace on the chance something useful is in there.

Read next

The rest of the case

Free ADR generator

Paste a pull request or describe the decision and get a formatted architecture decision record back. No account, nothing to install.

ADR vs wiki

Two formats that fail in opposite ways, and how to tell which failure you currently have.

Why agents need the why

A coding agent that cannot see the reason for a constraint will refactor it away. Decision records are how you stop that.

Before you ask

The questions we always get

01How is this different from asking an AI to summarise a pull request?+
A summary is disposable — you read it once and it is gone. This writes a durable record with a stable filename, links it to the notes it touches, and keeps it findable. The value is not the paragraph, it is that the paragraph is still there and still correct in eighteen months when somebody asks why.
02We already have Confluence. Why would we add anything?+
Your wiki is not stale because it lacks features. It is stale because writing the page is a separate act of will after the work is already done, and that act is the first thing to go in a busy week. The problem worth solving is the writing step, not the storage.
03Where do the notes actually live?+
Plain markdown in a directory you name, committed alongside your code. No database and no export step — you have a full copy at all times, and removing the tool leaves every note exactly where it was.
04Can it write code or open pull requests?+
No. It takes read access to the work you point it at and write access to one documentation directory. It cannot push a branch, open a PR, or modify anything outside that folder. The narrow write scope is the design, not a limitation waiting to be lifted.
05What stops it inventing a rationale that nobody actually had?+
Every claim in a note carries the commit, review comment or message it came from, and renders as a link back to it. Where a reason cannot be traced to something someone actually wrote, the section is left empty and flagged rather than filled in plausibly.
06Does this replace architecture decision records?+
It writes them. ADRs are a good format that teams abandon because maintaining them by hand competes with shipping. Keeping the format and removing the discipline requirement is the entire idea.

Stop paying twice for the same decision

Once when you make it, and again every time somebody has to reconstruct it. Try the generator on a pull request you already merged.

Try it free — no signupWhy agents need this