Master this essential documentation concept
A formal workflow in documentation or code management where proposed edits are submitted for review and approval before being merged into the main published version.
A formal workflow in documentation or code management where proposed edits are submitted for review and approval before being merged into the main published version.
Many documentation and engineering teams walk through change request processes during onboarding sessions, team standups, or recorded training calls — explaining who submits them, what triggers a review, and how approvals get routed before anything reaches the main branch. That context is genuinely useful, but when it only exists inside a video file, it creates a real problem.
When a contributor needs to submit a change request for the first time, they can't quickly scan a recording to find the step where you explained the approval threshold or the naming convention for the request title. They either watch the entire session or they guess — and guesses lead to rejected submissions, back-and-forth in review queues, and slower merge cycles.
Converting those recorded walkthroughs into structured, searchable documentation changes how your team interacts with that knowledge. A specific scenario: your team records a 45-minute onboarding call covering the full change request workflow. Once converted to documentation, contributors can search directly for "who approves a change request" or "required fields" and land on the exact paragraph — without rewatching anything.
That kind of accessibility makes your change request process easier to follow consistently, especially as your team scales or your workflow evolves and needs updating.
If your team regularly captures process knowledge through video, see how converting those recordings into structured documentation can support workflows like this →
A backend team deprecates a REST endpoint and introduces a new one, but the API documentation is updated ad-hoc by multiple writers simultaneously, causing conflicting edits, outdated examples, and no audit trail of who approved the change.
A Change Request workflow enforces that all documentation updates for the deprecated endpoint go through a formal review cycle, requiring sign-off from both the API developer and a technical writer before the new endpoint docs go live.
['Author opens a Change Request in the docs repository (e.g., GitHub PR) linking the deprecated /v1/users endpoint and the new /v2/accounts endpoint with updated code samples.', 'Assign the owning backend engineer as a required reviewer to verify technical accuracy of the new request/response schemas.', 'Assign the docs lead as a second reviewer to check tone, formatting, and adherence to the style guide.', 'After both approvals, merge the CR into the main branch, triggering an automated docs build that publishes the updated API reference.']
Zero conflicting edits reach production, the changelog captures exactly who approved the deprecation notice, and developers consuming the API see consistent documentation from day one of the new endpoint launch.
A compliance officer identifies that safety warning language in a medical device manual must be updated to meet updated FDA 21 CFR Part 820 requirements, but the team has no formal process to ensure the right stakeholders review the exact changed text before it ships.
A Change Request isolates the specific sections containing safety language, routes them to the regulatory affairs team and legal counsel for mandatory approval, and creates an immutable audit log proving the review occurred before publication.
['The technical writer creates a CR targeting only the Warning and Contraindications sections, tagging the changed paragraphs with the relevant regulation reference number.', 'The CR is assigned to the Regulatory Affairs reviewer and Legal reviewer as required approvers, with a 48-hour SLA enforced by the workflow tool.', 'Each reviewer leaves inline comments on the exact wording, and the author revises until both parties formally approve the CR.', "The approved CR is merged, and the version-controlled diff is exported as a PDF and attached to the device's Design History File for FDA audit readiness."]
The organization can demonstrate a complete, timestamped review chain for every compliance-related edit, reducing audit preparation time and eliminating the risk of unapproved safety language reaching end users.
A first-time contributor to an open-source project submits a large, unfocused documentation edit that rewrites multiple unrelated pages, mixes style conventions, and is difficult for maintainers to review or partially accept.
The project's Change Request process (via GitHub Pull Requests) enforces small, scoped submissions with a PR template, requiring contributors to describe what changed and why, enabling maintainers to review and merge only the valid portions.
["The project's CONTRIBUTING.md instructs new contributors to fork the repo and open one PR per logical change, using the provided PR template that includes fields for 'What changed', 'Why it changed', and 'Related issue number'.", 'The CI pipeline runs an automated linter (e.g., Vale) on the CR to flag style violations before a human reviewer spends time on it.', "A maintainer reviews the scoped CR, leaves specific inline suggestions using GitHub's suggestion feature, and requests changes if needed.", 'Once the contributor addresses all comments, the maintainer approves and merges, and the contributor is credited in the release notes.']
Average review time per contribution drops because CRs are focused and pre-validated by automation, and new contributors receive structured feedback that accelerates their understanding of project standards.
A product team rolls out a new dashboard feature behind a feature flag to 10% of users, but documentation for the feature is published immediately to all users, causing confusion and an influx of support tickets from users who cannot find the described UI.
A Change Request for the new feature documentation is created and approved in advance but held in a 'pending merge' state, configured to merge automatically when the engineering team merges the feature flag removal commit.
['The technical writer opens a CR with the new dashboard feature documentation as soon as the feature enters beta, linking it to the corresponding engineering Jira ticket.', "The CR is reviewed and fully approved by the product manager and UX writer, but the merge is blocked by a branch protection rule requiring the engineering 'feature-flag-removal' branch to merge first.", "When engineering merges the full rollout commit, the docs CR's blocking condition is cleared and it is merged automatically via a CI/CD pipeline hook.", 'A Slack notification is sent to the #docs-releases channel confirming the documentation is now live in sync with the feature.']
Documentation and feature availability are synchronized to within minutes of each other, eliminating the support ticket spike that previously accompanied every major feature launch.
A CR that modifies the authentication guide, the billing FAQ, and the API changelog simultaneously is nearly impossible to review meaningfully and creates a large blast radius if something is wrong. Keeping each CR focused on one logical change—such as updating all references to a renamed CLI flag—allows reviewers to apply relevant expertise and makes rollbacks surgical rather than destructive.
A CR description that says only 'Updated installation steps' gives reviewers no context about whether the change is correct or complete. Including the reason—such as 'Updated steps 3-5 because the legacy pip install path was removed in v4.2.0'—allows reviewers to validate the change against its stated purpose and helps future contributors understand the history in git blame.
Routing a CR about Kubernetes deployment configuration to a marketing writer who happens to be online will produce an approval that validates formatting but misses technical inaccuracies. Effective CR workflows use CODEOWNERS files or reviewer assignment rules to automatically route documentation changes to the engineer or subject matter expert who owns that product area.
Sending a CR to a human reviewer that contains broken internal links, style guide violations, or malformed code blocks wastes reviewer time on issues a machine can catch in seconds. Running automated checks—such as a Vale style linter, a link checker, or a Markdown formatter—as a required CI status check ensures human reviewers focus on accuracy, clarity, and completeness rather than mechanical errors.
Without a defined turnaround expectation, CRs stall in review limbo for days or weeks, blocking documentation releases and frustrating authors. Different reviewer types have different availability: a subject matter engineer may need 48 hours while a docs lead should respond within 24 hours. Publishing and enforcing these SLAs in the contributing guide sets clear expectations and allows authors to escalate appropriately.
Join thousands of teams creating outstanding documentation
Start Free Trial