How to keep your README updated when code changes

Every team has the same problem: someone merges a PR that changes how authentication works, adds a new environment variable, or replaces a key dependency — and the README still describes the old way. Nobody updates it. Not because they're lazy, but because it's not in the flow.

This is documentation drift, and it compounds over time. New engineers follow the README into dead ends. Senior engineers stop reading docs and just read code. Your documentation becomes a liability instead of an asset.

Why docs go stale

The problem isn't motivation — it's timing. When you're writing code, documentation feels like friction. When you're reviewing a PR, adding a docs update feels like scope creep. And once the PR merges, nobody circles back.

CI/CD has solved this for almost everything else in the development lifecycle: tests run automatically, lint runs automatically, security scans run automatically. Documentation is the last thing that still depends on individual developers remembering to do it.

The automated approach

The pattern that works: trigger a documentation review on every merged PR, not on developer memory.

Here's how it works at a high level:

1. A PR merges to main
2. Your CI/CD pipeline extracts the diff and relevant doc files
3. An LLM reviews the diff against the current docs and identifies what's outdated
4. A draft PR opens with the proposed documentation updates
5. A human reviews and merges (or edits and merges)

The key design choice is step 5: a human approves every change. The automation handles detection and drafting; the developer stays in control of what ships.

Setting it up with DocDr

DocDr implements this pattern as a GitHub Action. Add it to your workflow and it handles the rest: diff extraction, secret scanning (it never sends credentials to the API), LLM-powered doc generation, and draft PR creation.

name: Update docs on merge

on:
  push:
    branches: [main]

jobs:
  docdr:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2
      - uses: ianjamesburke/docdr@v1

That's the entire configuration. DocDr auto-discovers your documentation files on the first run and caches the mapping. No config file in your repo, no list of files to maintain.

What DocDr updates (and what it doesn't)

DocDr focuses on Markdown files that describe behavior: READMEs, setup guides, API docs, architecture docs. It doesn't touch comments in code, changelogs, or anything outside your configured doc targets.

On each run it gets the git diff for the merged PR, the current content of your doc files, and produces full-file replacements — not patches. You always see the complete document in the draft PR, never a confusing partial diff.

Common pitfalls

Trying to automate the review step. Auto-merging doc PRs removes the human check that catches LLM errors. The draft PR step exists for a reason — use it.

Updating docs too infrequently. Running DocDr only on releases means the queue of un-documented changes grows large, and the LLM has to infer too much context from a large diff. Per-merge is the right cadence.

Skipping the bootstrap. DocDr has a bootstrap mode that generates initial documentation from your repo structure. If your docs are already badly outdated, start there before switching to maintenance mode.

The result

Teams using this pattern report that they stop thinking about documentation as a separate task. The PR review process for the doc PR is fast — usually under two minutes — and the changes are targeted. The README stays current because the system keeps it current, not because someone remembered to update it.

That's the goal: remove documentation from the list of things that require willpower, and make it something that just happens in the background of your normal workflow.