How to Update Documentation Automatically When a PR Merges
If you run an engineering team long enough, you eventually have the same conversation about documentation. A developer ships a feature. The code is reviewed, tested, and merged. Two weeks later, a customer support ticket arrives asking how to use the new endpoint. The support manager checks the docs, finds nothing, and asks the engineering manager what happened. The engineering manager sighs, pings the developer, and the developer promises to write it up "when they have a minute."
They never have a minute.
The problem is not that developers hate writing documentation, though many do. The problem is that documentation is treated as a separate, downstream task from writing code. When a pull request merges, the code deploys automatically. The documentation does not. That gap between the code shipping and the documentation updating is where drift happens.
To fix this, you have to remove the gap. Updating documentation automatically when a PR merges means tying the documentation lifecycle directly to the software development lifecycle. It means the act of merging code triggers the creation, staging, or deployment of the corresponding documentation.
But "automatic" means different things depending on what you are trying to achieve.
Defining the Scope of Automation
When engineering leaders say they want automatic documentation, they usually mean one of two things.
The first is automatic deployment. In this model, the documentation is still written by humans, but it lives in the same repository as the code. When a developer opens a PR, they include the documentation changes alongside the code changes. When the PR merges, a CI/CD pipeline (a system that automatically tests and ships code) builds the documentation site and deploys it. This is the core of the docs-as-code philosophy. The deployment is automatic, but the generation is not.
The second is automatic generation. This is where the documentation itself is derived directly from the code or its metadata. When a PR merges, the system reads the changes and generates the documentation without human intervention.
In practice, a robust system uses both. You automate the generation of what can be generated, and you automate the deployment of what must be written.
Three Patterns for Implementation
If you are evaluating how to build this, there are three common patterns.
The Docs-as-Code Pipeline
This is the baseline. The documentation lives in Markdown or reStructuredText files right next to the source code. When a developer changes an API, they update the documentation file in the same commit. The CI pipeline runs a linter like Vale to check the style and a link checker to ensure nothing is broken. If the checks pass and the PR is approved, the merge triggers a build tool like Sphinx or MkDocs to generate the static HTML. The pipeline then pushes that HTML to a hosting provider like Read the Docs or GitHub Pages.
This solves the deployment gap. The documentation is always in sync with the deployed code because they share the same commit hash. But it still relies on the developer remembering to update the documentation file in the first place.
Generating Reference Docs from Code
For API references and SDKs, you can remove the human from the generation step entirely. Instead of writing separate documentation files, developers write structured comments directly in the code. In Python, these are docstrings. In JavaScript, it is JSDoc. For REST APIs, it is an OpenAPI specification.
When the PR merges, the CI pipeline runs a tool that extracts these annotations and generates the documentation. Sphinx's autodoc extension, for example, pulls Python docstrings and converts them into readable HTML. Swagger UI takes an OpenAPI JSON file and turns it into an interactive API console.
This guarantees that the reference documentation is perfectly accurate. If the code changes, the documentation changes. The developer only has to maintain the code annotations, which are right in front of them while writing the code.
Assembling Changelogs from Metadata
Release notes and changelogs are notoriously difficult to keep updated. The pattern here is to generate them from the exhaust of the development process: commit messages and pull request titles.
This requires discipline. Teams adopt a standard like Conventional Commits, where every commit message follows a specific format (e.g., feat: add user authentication or fix: resolve login timeout). When a PR merges, a tool like Semantic Release analyzes the commit history since the last tag, determines the next version number based on the commit types, generates a changelog summarizing the new features and fixes, and publishes the release.
The commit message becomes the raw material. The tool does the assembly.
The Governance Model
The risk of automatic generation is that you ship garbage at the speed of light. A poorly written docstring becomes a poorly written public API reference. A cryptic commit message becomes a confusing release note.
Research from DORA shows that documentation quality is a significant driver of organizational performance. Teams with high-quality documentation see massive multipliers in the benefits of technical practices like continuous delivery and trunk-based development. Teams implementing trunk-based development with above-average documentation quality see a 1,525% lift to organizational performance, compared to 36% for teams with below-average documentation quality. You cannot sacrifice quality for speed.
The solution is a governance model that separates generation from publication.
When a PR merges, the CI pipeline triggers the generation of the API references and the drafting of the changelog. But instead of deploying immediately to production, it stages the output. A documentation lead or product manager reviews the staged content, edits the generated release notes for clarity, adds narrative context, and approves the final publication.
Automation does the heavy lifting of extraction and assembly. Skilled humans do the validation and shaping.
A practical example: a developer merges a PR that touches an API endpoint. The commit message follows a structured template. On merge, CI triggers three actions. API reference docs regenerate from updated code annotations. A changelog entry is drafted from the commit metadata. A release note is queued in the staging environment. A documentation lead reviews the staged output, edits for clarity if needed, and approves publication. What is automatic: generation, staging, deployment. What is human: approval, edge case handling, narrative shaping.
If you want to implement this governance model without building the pipeline yourself, Doc Holiday generates release notes, changelogs, and API references directly from engineering workflows, providing a structured review and approval process for teams that want speed without sacrificing quality.
