"Your PR shipped. Your docs didn't. Here's the checklist that makes 'I forgot to update the docs' a thing of the past."
Let me paint you a picture. You'll recognize it.
A PR ships a new endpoint. Code review was thorough — three approvers, tests green, CI happy. Change goes to production. High fives all around.
Three weeks later, a developer files a support ticket. The docs say the endpoint returns user_id but it actually returns userId. One camelCase field. Three weeks of confused developers. Nobody remembered to update the docs, because of course nobody remembered to update the docs. The docs are always the thing you forget right before merge, right after "I'll add tests later."
Here's the thing that stings: this isn't a documentation team problem. It's a workflow problem. The person who knows the change best — the PR author — is the person best positioned to flag what needs updating. But nobody gave them a checklist, so they didn't.
Let's fix that.
Before we get to the full checklist, here's the version for teams that are honest about their attention spans. If your team does nothing else, do these three things:
That's it. Those three habits — search, test, flag — catch the vast majority of doc drift before it reaches production. Everything below is the full version for teams ready to be thorough.
Save this as a PR template, a saved reply, or pin it in your team channel. Every PR author runs through this before requesting review.
If the answer to any of these is yes, docs need updating. No exceptions, no "I'll do it next sprint":
If your PR only changes internal logic with zero external-facing impact, congratulations — you can stop here. Go get coffee.
This is where updates get missed, because a single API change is like pulling a thread. It unravels in places you didn't expect:
The rule of thumb: Search your docs repo for the endpoint name, the field name, and any parameter names that changed. Every result is a page that's potentially lying to developers right now.
Code examples are the most dangerous part of documentation. They break silently, and developers trust them completely. They copy-paste, it fails, and they blame themselves for twenty minutes before realizing the example was wrong.
If you can't test the examples yourself, flag them in the PR description so a reviewer or tech writer can. An untested example is a support ticket waiting to happen.
Beyond "does it work," check that the words still describe reality:
Even if you update the docs yourself, make the change visible:
The fastest way to make this stick is to embed a minimal version in your team's PR template. Add this to .github/PULL_REQUEST_TEMPLATE.md:
## Documentation Impact
<!-- Check all that apply -->
- [ ] No external-facing changes (skip docs section)
- [ ] New/changed endpoints or parameters — API reference updated
- [ ] Code examples verified against sandbox
- [ ] Quickstart/tutorials checked for affected content
- [ ] Changelog updated
- [ ] Tech writer tagged (if applicable): @_____
**Docs PR:** <!-- link if separate repo -->This adds 30 seconds to PR authoring. It prevents the "wait, did anyone update the docs?" Slack message three weeks later — the one nobody wants to answer because the answer is always no.
Checklists work. Until someone's in a rush, it's Friday at 4pm, and they click "merge" without looking. Here's what you can take out of human hands entirely:
Broken links are the easiest doc issue to catch automatically. No judgment calls, no edge cases — the link works or it doesn't:
# .github/workflows/docs-check.yml
name: Documentation Checks
on:
pull_request:
paths:
- 'docs/**'
jobs:
link-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Check for broken links
uses: lycheeverse/lychee-action@v2
with:
args: --verbose --no-progress './docs/**/*.md'
fail: trueA style linter catches the inconsistencies humans miss after reading the same docs for the hundredth time — different names for the same concept, passive voice hiding who does what, three capitalization styles for the same product name:
- name: Run documentation linter
uses: ekline-io/ekline-github-action@v6
with:
content_dir: docs/
ek_token: ${{ secrets.EK_TOKEN }}
github_token: ${{ secrets.GITHUB_TOKEN }}
reporter: github-pr-reviewThis posts review comments directly on the PR, the same way a code linter would. Because docs deserve the same treatment as code. (That's our whole thing, actually.)
If your code examples live in standalone files (they should), you can track when they were last updated relative to the API code they reference:
#!/bin/bash
# Check if any doc examples are older than related API files
for example in docs/examples/*.py; do
# Extract the endpoint from the example file
endpoint=$(grep -oP '(?<=/)v\d+/\w+' "$example" | head -1)
if [ -z "$endpoint" ]; then continue; fi
# Find the corresponding API route file
api_file=$(grep -rl "$endpoint" src/routes/ 2>/dev/null | head -1)
if [ -z "$api_file" ]; then continue; fi
# Compare last-modified dates
example_date=$(git log -1 --format="%ct" -- "$example")
api_date=$(git log -1 --format="%ct" -- "$api_file")
if [ "$api_date" -gt "$example_date" ]; then
echo "STALE: $example (last updated $(date -d @$example_date +%Y-%m-%d)) — API file $api_file changed $(date -d @$api_date +%Y-%m-%d)"
fi
doneIt won't catch everything. But it'll catch the obvious ones: API code changed two months ago, corresponding example hasn't been touched. That's a lie your docs are telling right now.
Sometimes stuffing doc updates into the same PR makes things worse:
Large refactors. If your code PR is already 800 lines, adding doc changes makes review a nightmare. Create a linked docs PR instead. Just make sure neither merges alone.
Docs in a separate repo. You can't include them in the same PR anyway. Link them. Set a team rule: code PR doesn't merge until the docs PR exists.
Uncertain scope. If you're not sure which docs are affected, don't guess and don't ignore it. Flag it: "Docs impact: needs investigation — changed the response format for /transfers." Let someone who knows the docs assess the full scope.
The worst outcome isn't "docs update in a separate PR." It's "nobody flagged the docs impact at all." That's how user_id becomes userId in production and nobody notices for three weeks.
Want to take the "remembering" out of documentation reviews? EkLine runs style, accuracy, and consistency checks on every PR automatically — so your docs get the same quality gate as your code. No human memory required.
