Course Preview
Documentation Review Workflows
Documentation review workflows are the structured process of checking content changes before they publish. Reviewers verify facts, catch broken links and untested examples, enforce style, and negotiate changes through pull requests and shared editing tools. The goal is an accepted change that readers can trust.
itTechnical communication and collaboration | OpenSkills.info
Course pathWalk it in order
Look it upDip in anytime
Go furtherLeaves this page
Intro
Documentation Review Workflows
Documentation review workflows are the defined process of checking a content change before it is accepted and published.
Why it matters
A single author can miss a broken link, an outdated command, or an example that no longer runs. Review adds a second set of eyes at the moment the change is small enough to inspect. The goal is an accepted change that is accurate, consistent, and safe to publish — not a perfect page produced by committee.
Review is most effective when it is a loop, not a gate: the author proposes a change, a reviewer examines the diff and comments, the author revises, and the reviewer rechecks. The change is rejected or merged based on the outcome.
Continue the course
This section is part of the paid course.
See pricing to subscribe, or log in if you already have access.
Where this skill leads
Relevant careers
See how this topic contributes to broader role-level skill maps.
Sources
- https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews
Supports
- The diff as the unit of review and inline comments anchored to lines
- Review states: comment, approve, and request changes
- A review applies to the version of the change at the time it is submitted
- The review loop and its merge-gate enforcement via protected branches
- https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
Supports
- CODEOWNERS names individuals or teams responsible for repository paths
- Code owners receive review requests for changes in their area
- https://docs.gitlab.com/ee/user/project/merge_requests/approvals/
Supports
- Merge approvals and eligible approvers as a merge gate in GitLab
- Required approvals and merge request approval rules
- https://kubernetes.io/docs/contribute/review/reviewing-prs/
Supports
- A working documentation review process: filtering open PRs, Netlify preview, inline review
- The review checklist used on Kubernetes docs (commands, results, structure, links)
- Re-review after revision and the "nit:" comment convention
- https://kubernetes.io/docs/contribute/participate/roles-and-responsibilities/
Supports
- Tiered review roles: Anyone, Member, Reviewer, Approver
- The /lgtm and /approve commands and their meanings
- https://learn.microsoft.com/en-us/contribute/content/how-to-review-pull-request
Supports
- A step-by-step documentation review workflow from understanding the change to re-reviewing the revised diff
- https://developers.google.com/tech-writing/one/documents
Supports
- The craft of reading a draft for the reader, separating blocking issues from nits
- Phrasing feedback the author can act on
- https://thegooddocsproject.dev/
Supports
- Community-maintained document review templates and checklists for review workflows
- https://thegooddocsproject.dev/about/
Supports
- The Good Docs Project formed around 2019 to produce templates and review practices
- Timeline description of the project's founding
- https://github.com/BubuAnabelas/awesome-markdown
Supports
- Discovery of the Markdown tooling ecosystem (linters, editors, converters, parsers)
- Placement of markdownlint, remark-lint, and textlint under Linters
- https://github.com/joho/awesome-code-review
Supports
- Discovery of articles, papers, books, and tools about review practice
- Awesome Links rationale for the community starting point
- https://github.com/readthedocs-examples/awesome-read-the-docs
Supports
- Example Read the Docs projects to learn from for structure and maintenance
- Awesome Links rationale
- https://github.com/DavidAnson/markdownlint
Supports
- Markdown style rules enforced automatically in CI and as a pre-commit hook
- Awesome Links rationale
- https://lychee.cli.rs/
Supports
- Fast, async link checking for Markdown, HTML, and other files as CLI, library, and GitHub Action
- Awesome Links rationale
- https://github.com/remarkjs/remark-lint
Supports
- Pluggable, rule-by-rule Markdown linting; each rule as its own plugin
- Awesome Links rationale
- https://en.wikipedia.org/wiki/Microsoft_Word
Supports
- Word for MS-DOS 1983 and Word 4.0 1987 with revision tracking
- Timeline description of revision marks in Word 4.0
- https://blog.google/products-and-platforms/products/workspace/happy-15-years-google-docs/
Supports
- Google Docs launch in October 2006
- Timeline description of Google Docs and its collaboration features
- https://github.blog/news-insights/oh-yeah-there-s-pull-requests-now/
Supports
- The GitHub pull request feature that launched in 2008
- Timeline description of pull requests
- https://www.iso.org/standard/43070.html
Supports
- ISO/IEC/IEEE 26511:2011 as the standard for user documentation management
- Timeline description of the standard's publication
- https://www.writethedocs.org/origin-story/
Supports
- Write the Docs founding and its origin story
- Timeline description of the community's start in 2013
- https://workspaceupdates.googleblog.com/2014/06/suggested-edits-in-google-docs.html
Supports
- Google Docs Suggesting mode introduced in June 2014
- Timeline description of real-time collaborative review
- https://about.gitlab.com/blog/feature-highlight-merge-request-approvals/
Supports
- Merge request approvals added to GitLab EE in 2015
- Timeline description of GitLab approvals
- https://github.blog/2015-09-03-protected-branches-and-required-status-checks/
Supports
- Protected branches and required status checks introduced on 2015-09-03
- Timeline description of merge-gate enforcement
- https://github.blog/news-insights/product-news/a-whole-new-github-universe-announcing-new-tools-forums-and-features/
Supports
- Pull request Reviews (approve or request changes) announced at GitHub Universe on 2016-09-14
- Required Reviews via protected branches
- Timeline description of formal reviews on GitHub
- https://github.blog/news-insights/product-news/introducing-review-requests/
Supports
- Review requests announced 2016-12-07, making it explicit who should review
- Timeline description of review requests
- https://github.blog/2017-07-06-introducing-code-owners/
Supports
- CODEOWNERS introduced to GitHub on 2017-07-06
- Timeline description of code ownership routing
- https://github.com/errata-ai/vale/releases/tag/v0.1.0
Supports
- Vale v0.1.0 released 2017-02-14
- Timeline description of Vale and prose linters
- https://github.com/
Supports
- GitHub Landscape placement as the pull-request review platform
- https://gitlab.com/
Supports
- GitLab Landscape placement as the merge request approvals platform
- https://www.atlassian.com/software/bitbucket
Supports
- Bitbucket Landscape placement for pull-request review with inline comments and approvals
- https://docs.google.com/
Supports
- Google Docs Landscape placement as the real-time collaborative editor with suggestions
- https://www.microsoft.com/microsoft-365/word
Supports
- Microsoft Word Landscape placement as the tracked-changes review editor
- https://www.atlassian.com/software/confluence
Supports
- Confluence Landscape placement for wiki-style page review
- https://www.notion.com/
Supports
- Notion Landscape placement for block-comment review in a workspace
- https://www.madcapsoftware.com/products/flare/
Supports
- MadCap Flare Landscape placement for structured authoring with a built-in review cycle
- https://paligo.net/
Supports
- Paligo Landscape placement for component-based content review
- https://www.acrolinx.com/
Supports
- Acrolinx Landscape placement for enterprise style checking at authoring time
- https://www.grammarly.com/
Supports
- Grammarly Landscape placement as an automated first pass on grammar and clarity
- https://textlint.github.io/
Supports
- textlint Landscape placement as a pluggable prose linter with per-rule enablement
- https://vale.sh/
Supports
- Vale Landscape placement as the command-line natural-language linter for Markdown
- https://www.gitbook.com/
Supports
- GitBook Landscape placement for repository-backed docs review through pull requests
- https://about.readthedocs.com/
Supports
- Read the Docs Landscape placement for pull-request preview builds as the render check