A real changelog is a small amount of work with an outsized return.

what it is for#

Deciding whether to upgrade. The single most common reason someone reads a changelog. They are on version 3.2, version 3.7 exists, and they want to know whether it is worth the risk.

Knowing what will break. The most important information you can provide, and the thing auto-generated release notes are worst at.

Debugging. "This started failing after we upgraded" — a good changelog turns that into "here is the change that caused it" in thirty seconds.

Finding out what exists. People discover features by reading changelogs. This is a real and underrated distribution channel for your own work.

why generated release notes are not enough#

A list of merged pull request titles has three problems.

It is written for the wrong audience. "Refactor connection handling" means something to the maintainer and nothing to the user. What changed for them?

It has no hierarchy. A breaking change and a typo fix appear as sibling bullets of equal weight.

It has no migration guidance. "Remove deprecated parse() method" tells you something broke. It does not tell you what to do about it.

the format#

Keep a Changelog is the established convention and it is good. The structure:

## [4.2.0] - 2026-07-22

### Breaking
- `Client.connect()` no longer accepts a positional timeout.
  Pass `timeout=` as a keyword.
      # before
      client.connect(host, 30)
      # after
      client.connect(host, timeout=30)

### Added
- `Client.ping()` for health checks without a full round trip (#412)
- Support for Unix domain sockets via `unix://` URLs (#398)

### Fixed
- Connections leaked when the handshake timed out (#405).
  If you saw file descriptor exhaustion under load, this was it.

### Deprecated
- `Client.legacy_mode` — will be removed in 5.0. Use `compatibility=`.

### Security
- Fixed a case where credentials could appear in debug logs (GHSA-xxxx-xxxx).
  Affects 4.0.0–4.1.3. Rotate credentials if debug logging was enabled.

the rules that make it useful#

Breaking changes first, always. That is what people are scanning for. Do not bury them under twelve feature bullets.

Include the migration. A breaking change without "do this instead" makes the reader open your source code. Two lines of before-and-after saves everyone time.

Describe the user-visible effect, not the implementation. Not "refactored the retry logic." Rather: "retries now use exponential backoff with jitter; if you relied on the previous fixed 1-second interval, set retry_delay=1.0."

Say who is affected. "If you use X, this changes for you. Otherwise nothing changes." Most readers can then stop reading, which is a service.

Link to the issue or pull request for anyone who wants detail. The changelog is a summary, not a substitute.

Date every release, in ISO format. Version numbers alone do not tell you whether you are two months or three years behind.

Write it as you go, not at release time. An Unreleased section at the top that each pull request adds to. Reconstructing a changelog from git history at release time is miserable and it is why changelogs get skipped.

the security section specifically#

If you fix a security issue, say so, with:

• Which versions are affected.
• What the impact is.
• Whether any action beyond upgrading is required.

That last one is the part that gets omitted and it is critical. "Upgrade to 4.2.0" is insufficient if credentials may have been exposed — the user also needs to rotate them, and they will not know unless you say so.

for internal projects#

The same file works for internal services, and the audience is your future self and the person who takes over the service.

The most valuable internal changelog entries are the ones that record a decision:

## 2026-07-14
- Switched from polling to webhooks for order status. Polling was
  costing ~40 requests/second against the vendor's rate limit and
  we were getting throttled during peaks.

Six months later, when someone asks why there is webhook infrastructure, the answer is in one place.

the return on investment#

Ten minutes per release. In exchange:

• Fewer support questions.
• Faster upgrades by your users, which means fewer people on old versions you have to support.
• Fewer surprised users after a breaking change.
• A record you can search when debugging.

There are not many ten-minute tasks with that profile.

The result is consistently: an architecture overview that is meaningless without context, a list of tools with no explanation of why, and no answer to any question a new person actually has.

what a new engineer actually needs, in order#

Day one: get something running.

Not understanding. Running. A new engineer who has the application running locally on day one is in a completely different position from one who is still fighting a dependency on day three.

This section should be a numbered list of commands that work. Tested. On a clean machine. Recently.

## get it running

1. Install prerequisites:  `brew bundle`   (or the equivalent — see below)
2. Copy the environment:   `cp .env.example .env`
3. Get secrets:            `./scripts/fetch-dev-secrets` (needs VPN)
4. Start dependencies:     `docker compose up -d`
5. Migrate:                `./scripts/db-reset`
6. Run:                    `pnpm dev`

You should see the app at http://localhost:5173 with seeded data.
Log in with dev@example.com / password.

If step 3 fails with "unauthorized", you need to be added to the
dev-secrets group — ask in #eng-onboarding.

That last paragraph — the anticipated failure with its resolution — is the part that separates a document that works from one that does not. Every step that has ever failed for anyone should have a note.

Day two: make a change and see it.

A guided first change. Something trivial and real: change a label, add a field, fix a typo in a template. All the way through: edit, test, review, merge, deploy.

The point is not the change. It is that they have now executed the entire delivery pipeline once, so every subsequent change is a variation on something they have done.

Day three to five: the map.

Now the architecture overview, and now it means something, because they have seen the system run.

Keep it to a page. What are the major pieces, what does each do, how do they talk. A diagram. Where the code for each piece lives.

Not a complete description. A map, at the resolution of "which building do I go to."

Week two: the why.

The decisions that are not obvious from the code. Why the database is structured that way. Why there is a queue between those two services. Why that module is frozen. Why the obvious approach to X does not work.

This is the highest-value and least-written documentation in any organization, because it exists only in the heads of people who were there. When they leave, it is gone, and the next person spends a year rediscovering it — usually by proposing the obvious approach and being told no.

the sections everyone forgets#

The glossary. Every organization has jargon: internal product names, acronyms, words used with a specific local meaning. A new person hears twenty of these in their first week and cannot ask about all of them without feeling stupid.

Write them down. This is a thirty-minute task with an outsized payoff.

Who to ask about what. Not the org chart. "Payments: ask Priya. Deploy pipeline: #platform-help. Anything about the legacy importer: Marcus, and be warned it is complicated."

The things that will surprise you. The test suite that fails on the first run until you seed a fixture. The service that takes four minutes to start. The one flaky test everyone knows about. The staging environment that resets on Sundays.

Every codebase has these. Writing them down converts "this is broken and I do not want to admit I cannot fix it" into "oh, that is expected."

What not to touch. Frozen modules, generated files, anything requiring a specific review.

the maintenance mechanism#

Onboarding docs rot faster than any other documentation, because the people who would notice the errors are the ones who no longer read it.

The fix: the last person onboarded owns it.

Every new engineer's first task is to follow the document, fix everything that was wrong, and add the things they had to ask about. Then they own it until the next person arrives.

This works because their frustration is fresh and their perspective is exactly the target reader's. It is the only mechanism I have seen that keeps these documents accurate.

the test#

Hand it to a new engineer and do not help them.

Time how long until they have the application running. Note every question they had to ask. Each question is a gap, with a measured cost.

Then fix them, and repeat with the next person.

Most teams have never done this and would be surprised by the result.

A design doc that works has a different shape, and the shape follows from being honest about why you are writing it.

why you are actually writing it#

Three reasons, and they want different documents:

To think. Writing forces you to discover that your plan has a hole. This version is for you and can be messy.

To get input before it is expensive. The highest-value function. You want the person who knows the thing you do not know to tell you before you build.

To create a record. So that in two years, someone can find out why.

Most templates optimize for the third and produce documents that fail at the second. The record is only worth having if the decision was good, and the decision is good because of the input.

the format#

One page. Two if the problem genuinely needs it. Structured so a reader can stop after any section and have gotten something.

Problem. What is wrong right now, with evidence. Not "we should improve X" — what breaks, how often, who it affects. If you cannot state the problem concretely, the design is premature.

Goals and non-goals. The non-goals are the important half and almost always missing. "This does not address the reporting pipeline" prevents forty comments about the reporting pipeline.

Proposal. What you are going to build, in enough detail to disagree with. Interfaces, data shapes, the sequence of operations. A diagram if the shape is not obvious in prose.

Alternatives considered. Two or three, each with one honest sentence about why not. This is the section that gets the good comments, because it is where a reader sees the option you dismissed for a reason they know is wrong.

If your alternatives section contains obvious strawmen, experienced readers will notice and discount the whole document.

Risks and open questions. What might go wrong. What you are unsure about. This is where you ask for help explicitly, and it is where the people who know things will engage.

Rollout. How it ships, how it is verified, how it is rolled back. A design without a rollback plan is not finished.

That is it. Under a thousand words for most things.

the things that make people not read it#

Length. Past about two pages, readership drops sharply. If you need more, put the detail in an appendix and keep the main document short.

Burying the proposal. If the reader has to get through three pages of background before learning what you want to do, they will not.

No clear ask. Say what you want. "I need someone who knows the payment path to confirm the idempotency assumption in section 3" gets a response. "Please review" does not.

Passive voice throughout. "It was determined that" hides who decided and why. It also reads as evasive, because it usually is.

No deadline. "Comments by Thursday, I will start Friday" produces comments by Thursday. An open-ended review produces comments never.

the review that works#

Ask specific people specific questions. Not "posting this to the channel." Three named people, each with a sentence about why you want their input.

Give a real window. Three to five days. Long enough to fit into someone's week, short enough to stay on the top of the pile.

Timebox the meeting, if there is one. For a contentious design, a 30-minute discussion after people have read it resolves more than two weeks of comments. For an uncontentious one, do not have a meeting.

Record the decision at the top when it is made. A resolved design doc should start with "Decision: we are doing X, decided 2026-03-18, because Y." The person finding this in 2028 wants that sentence and nothing else.

the thing that makes them worth writing#

The value is not the document. It is that you discovered the flaw while writing rather than while implementing, and that someone who knew something told you before you had built the wrong thing.

If you write a design doc and nothing changes as a result, either your design was already right — possible, uncommon — or nobody engaged, and the process is theater.

Measure it that way: how many of your design docs changed the design? If the answer is none, stop writing them in this format and figure out what would actually get you input.

That pause is the entire problem.

the four kinds, and why mixing them fails#

The taxonomy that fixed documentation for me — and it is not mine, it is the Diátaxis framework — is that there are four distinct kinds and they have incompatible goals.

Tutorials teach a beginner by having them do something that works. The goal is a successful experience, not completeness. A tutorial that mentions every option has failed. It should be prescriptive, opinionated, and it should work exactly as written, every time.

How-to guides help someone accomplish a specific task they already understand. "How to configure TLS." Goal-oriented, assumes competence, skips explanation.

Reference describes the machinery precisely and completely. Every parameter, every return value, every error. Boring by design. Generated where possible.

Explanation provides understanding. Why is it designed this way? What are the trade-offs? What is the mental model? This is the kind that is almost always missing and the kind that most reduces support burden.

Most documentation fails because it tries to be all four at once. A tutorial that stops to explain architecture loses the beginner. A reference page with a narrative is hard to scan. Separate them, label them, and each one gets better.

what "staff it like a product" means#

One named owner. Not "the team." A person whose review includes it.

A budget in the sprint. Documentation work sized and scheduled alongside features, not appended to the end of a ticket where it gets cut.

Metrics. Support tickets that a doc would have prevented. Search queries with no results. Time-to-first-successful-request for a new user. Page-level feedback. Every one of these is measurable and almost nobody measures them.

A definition of done that includes it. A feature is not shipped until it is documented. This is either enforced or it is a slogan; there is no middle.

the practices that actually move the needle#

Docs live with the code. Same repository, same pull request, same review. Documentation in a separate wiki drifts within one quarter, guaranteed, without exception.

Test the examples. Every code sample in your docs should be extracted and run in CI. Broken examples are worse than no examples — they destroy trust in the whole document, and every set of docs has them, because they were correct when written.

Write the failure cases. The single highest-value section in any documentation is "common errors and what they mean." This is what Stack Overflow existed to provide and it is the thing your docs almost certainly lack.

Go read your support queue. Every recurring question is a documentation gap with a measured frequency attached.

Date and version everything. "This page describes v4.2, last updated 2026-01-15." Undated documentation is untrustworthy documentation, because the reader cannot tell whether it is current.

Make the first example work. The single most common documentation failure: the quickstart does not run. Someone changed a default, renamed a parameter, required a new config field. Test the quickstart in CI, on a clean environment, on every release.

the argument that gets budget#

Documentation is deflection. Every question answered by a doc is a question not asked of an engineer.

Count your support load. Estimate the fraction that is documentation-shaped — "how do I," "what does this error mean," "does it support." In most organizations it is more than half.

Now price that in engineer-hours. That is your documentation ROI, and it is usually large enough to fund a technical writer, which is the actual right answer and which almost nobody does.

the new reason it matters#

Your documentation is now also a model's training data and a model's retrieval corpus.

When a developer asks an assistant about your library, the answer is synthesized from your docs. If your docs are wrong, incomplete, or ambiguous, the assistant confidently produces wrong code, and the user blames your library.

You have less control over how your project is explained than you did three years ago, and the only lever you have is the quality of the source material.

That is a strange new incentive and it is the strongest argument for good documentation that has ever existed.

The names varied — AGENTS.md, CLAUDE.md, .cursorrules, .github/copilot-instructions.md — and the format did not. It is prose. The model reads it. That is the whole protocol.

A convention that emerges independently in five products in one year is telling you something about the shape of the problem.

what actually belongs in it#

I have written and rewritten these a dozen times. The version that works is shorter than you think and more specific than you want.

Commands. The exact invocations. Not "run the tests" — the command, including the flags, including how to run one test file.

## commands
- install: `pnpm install --frozen-lockfile`
- test: `pnpm vitest run`
- test one file: `pnpm vitest run src/foo.test.ts`
- typecheck: `pnpm tsc --noEmit`
- lint: `pnpm biome check --write .`
- dev server: `pnpm dev` (port 5173)

This section alone eliminates most wasted agent turns. Without it, the agent guesses, guesses wrong, and spends four tool calls discovering your test runner.

Non-obvious structure. Where things live, when it is not inferable. "Database migrations are in db/migrations and must be created with pnpm db:new, never by hand." "The legacy/ directory is frozen — do not modify it."

Conventions that a linter does not enforce. If your linter catches it, do not write it down; the linter will tell the agent. Write down the things that are policy rather than syntax: "prefer composition over inheritance in src/domain", "all public functions in api/ need a docstring", "we do not use default exports".

Things that will break. "Do not run pnpm build — it takes 12 minutes and is not needed for tests." "The integration tests require Docker; skip them if it is not running." "Never modify schema.sql directly."

Boundaries. What the agent may not touch without asking. Production configs, migration files, anything with a security review requirement.

what does not belong#

Your entire architecture document. The agent reads this every session. A three-thousand-word essay costs tokens on every single request and dilutes attention across a lot of text that is irrelevant to most tasks.

Keep it under about 200 lines. If you need more, put it in a separate document and reference it: "for the event pipeline design, read docs/events.md before changing anything in src/events/."

Anything the code already says. Do not restate the type signatures. The agent can read.

Aspirations. "We value clean code" is not an instruction. "Functions over 40 lines get split" is.

Rules you do not actually follow. If the codebase contradicts the file, the codebase wins in the model's attention, and now your instructions are noise.

the part I did not expect#

Writing these has improved my documentation for humans.

The discipline of writing "here is exactly how to run the tests, here are the things that will surprise you, here is what not to touch" is precisely what a new engineer needs on day one, and it is precisely what most onboarding documents fail to contain because they were written by someone who already knew.

An agent is an infinitely patient new hire who will follow instructions literally and never ask a clarifying question out of politeness. That turns out to be an excellent test of whether your instructions are any good.

Several teams I know have merged their onboarding doc and their agent file into one. That is the correct end state.

the standardization question#

There is an ongoing effort to consolidate on AGENTS.md as the common name, with tools reading it as a fallback. That would be good and it is a coordination problem, which means it will take longer than it should.

In the meantime: write one file, symlink the rest. It costs nothing.

ln -s AGENTS.md CLAUDE.md

You will throw most of it away. That is fine. The value is in what happens while you write it.

what it forces#

A name for the thing. If you cannot name it in one sentence, you do not know what it is. "A library for X" where X is three clauses joined by "and" is three libraries.

A first example that fits on a screen. This is the brutal one. Write the code a new user types first. If it needs eleven lines of setup before anything happens, your API is wrong, and you found out before you built it rather than after.

# if this is your example, stop and redesign
client = Client(config=Config(
    auth=AuthProvider(strategy=Strategy.OAUTH, ...),
    transport=Transport(pool=Pool(size=10), retry=RetryPolicy(...)),
    serializer=JsonSerializer(...),
))
result = client.get_resource(ResourceRequest(id=ResourceId("x")))

# if this is your example, you are probably fine
client = Client(api_key=key)
result = client.get("x")

An explicit list of non-goals. Every project has them and most only discover them in a GitHub issue eighteen months later when someone asks for a feature that would break the design. Writing them down early is the cheapest scope control that exists.

Error cases described in prose. "If the token is expired, X happens." Writing that sentence often reveals that you have not decided what X is, and the decision is much cheaper now.

why it works better than a design doc#

Design documents are written for reviewers. READMEs are written for users. The audience difference changes everything.

A design doc rewards completeness, so it grows sections about alternatives considered and migration strategies and rollout phases, and by page six nobody including the author is thinking about the interface anymore.

A README rewards clarity from the outside. It cannot contain your internal rationale, because users do not care. It can only contain what the thing does and how to use it, which is exactly the part that is expensive to change later.

the internal-service version#

This works for services too, and possibly better.

Write the endpoint documentation before the endpoint. Write the example request and the example response. Write the error codes and what each one means.

Then send it to the team that will consume it — before you build anything. The feedback you get in that thread is worth more than any amount of code review after the fact, because at that point changing the interface is free.

Half the API design mistakes I have watched happen were mistakes that the consuming team would have caught in ninety seconds if anyone had shown them the shape first.

the objection#

"I do not know what it does yet, that is why I am building it."

Sometimes true. Exploratory work where the shape is genuinely unknown should be exploratory, and forcing a README onto it is cargo cult.

But be honest about which mode you are in. Most of the time you do know roughly what it does, and "I will figure out the interface as I go" means "I will discover the interface from whatever was convenient to implement," which is how you end up with a function that takes eleven positional booleans.

the actual test#

When you finish, read the README as if you had never seen the project.

If your reaction is "I do not understand what problem this solves," you have learned something enormously valuable for the cost of twenty minutes and no code.

That is the best exchange rate in software.