A pull request checklist for docs

Why put docs in the pull request?

Because the pull request is the only moment when the change, the person who made it, and a reviewer are all in one place. A week later, nobody remembers that the reminders setting moved. A docs question in the pull request turns “update the docs sometime” into a decision someone makes now.

It doesn't mean engineers write the help center. It means they flag what changed for customers, in a sentence, so whoever owns the docs can act on it.

What should the docs checklist ask?

Keep it to three questions: does this change anything a customer sees or relies on, which article describes it, and what exactly changed. Specific questions get honest answers; a generic “docs updated?” checkbox gets ticked by reflex.

## Docs impact

- [ ] No customer facing change (internal refactor, tests, tooling)
- [ ] Changes something customers see or rely on:
  - What changed, in one sentence:
  - Article(s) affected (link), or “needs a new article”:
  - Renames a setting, label, or field? Old name → new name:
  - Changes a limit, default, or price?
  - Makes a screenshot outdated?

The old name → new name line matters more than it looks: renames are the most common cause of articles that quietly stop matching the product.

Which changes need a docs update?

Anything that changes what a customer sees, does, or can rely on needs a docs check. Internal changes don't. The gray area is bug fixes: if an article described the buggy behavior as intended, the fix makes the article wrong.

Who writes the docs update?

The engineer describes the change; the docs owner writes the article. That split works on small teams because each person does the part they're best placed to do. The engineer knows what changed; the docs owner knows how customers talk and where the article lives.

For small, mechanical changes, like a renamed label or a new limit, the engineer can edit the article directly in the same pull request if docs live in the repository, or link the help center article for the owner to update. For anything that needs explaining, the one sentence summary in the checklist is enough to start from.

How do you keep the checklist from becoming a checkbox?

Make the questions specific, review the answers like code, and track the misses. A checklist works when someone reads it; it fails when it's a ritual.

• Ask for the article link, not a yes or no.
• Reviewers check the docs section like any other part of the change.
• When a “the docs are wrong” ticket arrives, find the pull request that caused it and look at what its checklist said.
• Keep the section short. Every extra question lowers the quality of the answers to the rest.
• Revisit it after a month: drop questions nobody answers well, sharpen the ones that catch real changes.

How do you add it to GitHub?

Create a file named .github/pull_request_template.md in your repository with the docs section, alongside whatever else your template asks. GitHub fills it into every new pull request automatically.

## What changed


## Docs impact

- [ ] No customer facing change
- [ ] Customer facing change:
  - What changed, in one sentence:
  - Article(s) affected, or “needs a new article”:
  - Old name → new name (if anything was renamed):

If you use several templates, add the docs section to each one that covers product changes. GitLab and Bitbucket support merge request and pull request templates the same way.

Can a tool fill in the checklist for you?

Yes, and it's often more reliable than a person in a hurry. A tool can read the diff of a merged pull request, decide whether customers would notice, find the articles that describe the changed behavior, and propose the edit. The checklist still helps: the engineer's one sentence summary is useful context, and it keeps the team thinking about customers.

Some teams also want the docs impact visible before merge, as a comment on the pull request. That's useful for catching changes that need a decision, like whether a renamed feature should keep its old name in the docs for a while.

How does usedocs handle this?

usedocs screens every merged pull request and release. When a change affects something an article describes, it proposes an edit to that article with the pull request, the files, and a one line reason attached; when no article fits, it can draft a new one. Edits wait in one review queue and nothing publishes without approval.

Comments on pull requests are opt in: turn them on and usedocs adds one comment to a pull request that changes what customers read, listing the affected articles, so engineers see the docs impact before merge. It's off by default.

Related guides