Most documentation lives in Git. The review of that documentation usually doesn't, and that's the problem.
Docs-as-code is a great pattern for writers: version control, branches, peer review, single source of truth. But the moment you need a PM, a Legal counsel, or a subject matter expert to read and comment on changes, the workflow falls apart. Raw Markdown diffs are unreadable to anyone who isn't an engineer. The fallback is Google Docs, or Confluence, or email threads, or copy-pasted Slack messages. Then someone has to manually reconcile all that feedback back into the actual files. The drift compounds. Reviews slip. PRs sit.
This guide is for the people who own that mess: tech writers, docs leads, DevRel managers, anyone who's responsible for shipping accurate documentation and can't get sign-off without playing Tetris with twelve tools.
What follows is the long version of what we've learned working with documentation teams of every size. The short version: review the docs where the docs live, render the content the way readers will see it, and stop forcing reviewers to learn Git syntax. The rest is detail.
What docs-as-code review actually is
“Docs-as-code” started as shorthand for treating documentation like source code: stored in a Git repository, written in a plain text format (usually Markdown, MDX, or AsciiDoc), built and deployed through a CI pipeline. The big sites all use some version of it. Stripe, Twilio, Linear, Vercel, GitHub itself. The benefits are obvious once you've worked in the model: pull request workflows, branching, automated checks, deploy previews, history that's actually useful.
Docs-as-code review is the part of the workflow where someone other than the writer reads a change and decides whether it ships. In a pure-engineering org, that's a peer engineer reviewing the PR. In a docs org, the reviewers are a mix: another writer, an engineer who owns the feature being documented, a PM, a Legal counsel, sometimes a customer success person, sometimes an external SME.
The peer-engineer case works fine. GitHub's PR interface was built for it. The other cases break, and that's where most teams hemorrhage time.
The breakdown isn't subtle. A PM clicks the PR link, sees a green-and-red diff of Markdown, doesn't understand what they're looking at, and either bounces or leaves a comment like “looks good I guess.” That's not review. That's a rubber stamp on something they couldn't read. And it's expensive: you've used up a review cycle without getting any actual feedback, and now the PR ships with whatever errors the writer missed.
Docs-as-code review, done right, has to bridge two worlds. The source-of-truth lives in Git, in the format engineers can work with. The review experience has to live somewhere a non-engineer can actually function. Most teams have not solved this. Most teams are still patching it with Google Docs.
Why a GitHub diff isn't enough
GitHub's pull request UI is, genuinely, a great code review tool. The line-by-line diff, the syntax highlighting, the threaded comments anchored to source lines: all of that works for engineers reviewing engineers' code.
For documentation, every one of those features is a problem.
Line-by-line diffs strip out the visual structure of the content. A heading becomes a flat string with a hash in front of it. A bulleted list looks like a sequence of dashes. Tables look like punctuation. Frontmatter looks like YAML noise. The reader can't see what the page will actually look like once it's built. They can't tell whether a section reads well, whether the table flows, whether the new screenshot lands in the right place. They're squinting at the recipe instead of tasting the dish.
The comment model is the second problem. GitHub comments are anchored to lines of source. A non-engineer reviewer thinks about sentences and paragraphs and ideas. Asking a Legal reviewer to “leave a comment on line 47” is asking them to work in a paradigm they don't recognize. Even when they manage it, the comment thread is hard for the writer to act on, because the reviewer is often referring to content that has been moved or rewritten by the time the writer comes back to it.
The third problem is psychological. Non-engineers walk into a GitHub PR and feel, immediately, that they're in someone else's house. The chrome is technical. The buttons say “Files changed” and “Conversations” and “Checks.” The diff has filenames like docs/concepts/auth.mdx. They don't know which file matters. They don't know what to click. They don't want to break anything. So they leave.
We dug into this in more detail in Why Non-Technical Reviewers Won't Use GitHub, but the short version is that the interface itself is the bottleneck. No amount of training fixes it. The fix is to render the content the way the reviewer expects to see it, and let them comment in the way they already know how to comment.
The four costs of getting it wrong
There are four costs. Most teams notice only one of them, usually the wrong one.
Writer reconciliation time. This is the cost most writers feel and the cost most engineering leads dismiss. When feedback lives in Google Docs, Confluence, email, or Slack, somebody has to copy each suggestion back into the Markdown source. For a single typical docs PR reviewed in Google Docs, that's somewhere between 60 and 90 minutes of writer time. Twenty PRs a month, twelve months a year, that's 240 to 360 hours per writer per year spent on glorified data entry. At a fully-loaded $85 an hour, you're looking at $20,000 to $30,000 a year of a senior writer's salary going to ferrying suggestions between two tools.
Reviewer friction time. Every non-engineer reviewer spends extra minutes on every PR just figuring out the review tool. Google Docs is fine but the doc is stripped of formatting. Confluence mirrors go stale. Email threads fragment. GitHub native review is the worst, because most non-engineers either give up or take 45 minutes interpreting a raw diff. Three reviewers per PR, twenty PRs a month, four hours of reviewer time gone per PR before any actual reviewing happens.
Release delay. Every extra back-and-forth round between writer and reviewer adds days. The more friction in the review medium, the more rounds, the longer the wait. We see teams adding two to four days of pure waiting per PR just because the review medium is wrong.
Stalled reviews. Some percentage of assigned reviewers never respond. In GitHub native review for docs, the dropout rate for non-engineers is often above 50%. Each stalled review means chasing, escalating, or pushing without sign-off. None of those are good.
We built a free calculator at draftview.app/cost-of-docs-drift that puts a dollar figure on all four for your specific team. Plug in your real numbers. The math is shown next to every output so you can sanity-check it. For most teams the number is bigger than they expected. That's the point.
For a deeper look at the Google Docs trap specifically, see The Hidden Cost of Reviewing Docs in Google Docs and the short launch post for the calculator, The Real Cost of Docs Review Drift.
Picking a review tool
There is no review tool that is right for every team. There are tools that are right for specific situations. The question is which situation you're actually in.
Start with one question: where does the content live now? If it's in a Git repository, written in Markdown, MDX, or AsciiDoc, then docs-as-code is a real fit and you should pick a review tool that respects that. If it lives in a wiki or a docs platform that doesn't sync to Git, the question is different (and usually the answer is: move it to Git first, then pick a review tool).
Assuming the content is in Git, here's a rough decision tree.
If your reviewers are all engineers with GitHub accounts and time to learn the diff view, then GitHub's native PR review is fine. Most engineering-led docs teams stay here for years and it works. One trap: do not assume your reviewers are this person just because you are. If even one of your reviewers is a PM, a Legal reviewer, or a non-engineer SME, GitHub's native UI is not going to work for them, no matter how patient they are. See DraftView vs GitHub PR Review for the side-by-side.
If your reviewers are mixed (some engineers, some not), and you've been bridging the gap with Google Docs, you're paying the reconciliation cost on every PR. The fix is a tool that lets non-engineers review the rendered content in a way that syncs back to the PR. We obviously think DraftView is the right answer here (we built it for this exact case) but the Google Docs comparison lays out the trade-offs honestly.
If your reviewers live in Confluence because that's where the rest of the company's documentation lives, the temptation is to mirror your docs there. Don't. Or, if you must, understand that you're building a two-system problem: every change has to be made in both places, and the systems will drift the moment you stop paying attention. The DraftView vs Confluence comparison goes into why this fails so reliably.
If your reviewers prefer Notion (this is more common at startups), the same logic applies. Notion is a fine tool. It's just not a docs-as-code tool. Trying to make it one is a tax on your writers. DraftView vs Notion covers the specifics.
If you want a full overview of how different tools stack up, we keep the comparison set at draftview.app/compare. We built DraftView, so the comparisons are biased in the sense that we picked which tools to compare against. They're not biased in the sense of misrepresenting how the other tools work. We've tried to be fair. Read them yourself and judge.
What a good docs review actually looks like
If you strip out the tooling, the review you want goes something like this.
A writer opens a PR with a change. The PR triggers a build that produces a preview of the rendered page, exactly the way it will look in production. The reviewer gets a link. They open it and see the page rendered: headings, lists, tables, code blocks, screenshots, all of it. They read it the way a real reader would. When they spot something to change, they highlight the text and type the change. They might add a comment. They might suggest specific replacement text. They might just ask a question.
The writer comes back, sees each suggestion attached to the exact source line it concerns, accepts the ones that make sense, rejects the ones that don't, and replies to the questions. The reviewer gets notified. They re-review. The writer merges.
That's it. No copy-pasting. No reconciliation. No second source of truth. Every suggestion is attached to the actual Markdown, with proper attribution in Git history. The reviewer doesn't need to know anything about Git or Markdown to make a useful suggestion.
The version of this that GitHub gives you natively works for engineers. The version that Google Docs gives you breaks the Git connection. The version we built for DraftView is meant to give you both: a visual, Google Docs-style review for non-engineers, with suggestions that sync back to the PR as native GitHub Suggested Changes.
Some teams build their own version of this with a homegrown stack: a static site preview hosted somewhere, a Slack channel for comments, a writer who consolidates feedback by hand. That works at very small scale. It does not scale to ten PRs a week.
The full play-by-play for a team adopting this pattern is in our docs-as-code review workflow guide. If you want to see what the rendered version feels like before committing to anything, try DraftView on any public PR without signing in. The whole point of that page is to let you evaluate the experience on a PR you already know.
Getting non-engineers to actually engage
The hardest part of docs review at most companies isn't the writing. It's the human problem of getting PMs and Legal counsels and SMEs to actually read the PR and leave useful feedback, on time, in a format the writer can act on.
There are three things that consistently move the needle.
Show them rendered content, not source. This is the single biggest lever. A reviewer who sees a formatted page in their browser is in a familiar context. They're reading the documentation the way they read every other document at the company. They engage. A reviewer who lands on a GitHub diff is in an unfamiliar context. They might engage. They probably won't. The fix is technological, not behavioural. Stop trying to train non-engineers to use Git. Start showing them the content the way they expect to see it.
Let them comment in plain language. “This sentence is confusing. Can we say it more like X?” That's how a Legal reviewer wants to give feedback. Not “line 47, suggestion: ...” Inline comments anchored to text passages, not line numbers, are the right primitive. Whatever tool you use should make this easy.
Cut the cycle time. Reviewers respond on the timescales you make easy. If your tool requires them to log into GitHub, navigate to a PR, find the right file, and parse a diff, they will respond on the timescale of “I'll do it when I have time,” which is “never.” If your tool sends them a link they can open in one click and review in five minutes, they will respond on the timescale of “I'll do it right now.”
For the long version of why this happens, Why Non-Technical Reviewers Won't Use GitHub goes deep. The piece on getting SME sign-off without leaving GitHub covers the specific case of subject matter experts, who tend to be the slowest-responding reviewer class for predictable reasons.
The thing nobody tells you: a reviewer who feels stupid in your tool will never tell you they feel stupid. They'll just stop responding to your review requests. By the time you notice, you've already lost them as a useful reviewer. Treat the tool friction as a first-class problem.
External reviewers
The hardest review case is the reviewer who isn't in your company at all.
Outside legal counsel reviewing terms of service updates. A localisation agency reviewing translated content. An external SME you've hired for a specific project. A customer advisory board member sanity-checking a launch announcement. All of these people need to read and comment on documentation that lives in your GitHub repository. None of them have GitHub accounts. None of them are getting one.
The default fallback is, again, Google Docs. The writer copies the content out, sends a link, collects feedback, applies it back. Two weeks later the legal team asks for a second round. The Google Doc has diverged from the source. The writer reconciles again. The audit trail is fragmented across three tools. If anyone ever asks “who approved this language?”, the answer is “I have an email somewhere.”
This is the case DraftView's external review links were built for. The owner creates a password-protected link with an expiry date and a submission cap. The reviewer gets the link. They open a rendered preview of the PR, leave inline suggestions and comments, submit. The owner reviews the feedback in DraftView, decides what to push to the PR, and pushes it. The reviewer never touches GitHub. The audit trail is intact. The link can be revoked at any time.
We wrote a longer post on sharing docs PRs with external reviewers without a GitHub account that walks through the full flow, including how to think about the security model.
A note on the security model, because it matters: external review links are scoped to the PR, password-protected, time-limited, and revocable. They're not the same as inviting someone to your GitHub org. They're closer to a Google Doc share link, but with proper logging and an audit trail attached.
Linting and pre-review hygiene
Reviews go faster when the obvious problems are already fixed. That's what linting is for.
Modern docs linters catch most of the things a human reviewer would call out: passive voice in places it shouldn't be, prohibited terms, style guide violations, inconsistent capitalisation, broken links, missing alt text on images. Vale is the most widely used one. Its strength is the rule packs: Microsoft, Google, Red Hat, plus whatever custom rules your team writes. Most docs teams that adopt Vale see their review cycle times drop noticeably within a few weeks. The reviewers stop getting bogged down on style and start commenting on substance.
The friction with Vale historically is that it runs on the command line. Writers have to install it, configure it, run it before pushing. Some teams script it as a pre-commit hook. Some run it in CI. Either way, there's friction for the writer.
We built ProseLint Web (free, browser-based, no install) as a way to get Vale linting without the setup tax. Same rule packs, same checks, runs entirely in your browser. We use it for our own content. The longer post on the workflow is Lint Your Docs Before the Pull Request, which covers why pre-review linting is the single highest-leverage hygiene practice for docs teams.
There's also the question of which checks belong in CI versus which belong as advisory tools. The rule of thumb: anything that has to be true for the doc to ship belongs in CI as a blocking check. Anything that's a strong suggestion but might have legitimate exceptions belongs in an advisory tool that runs before the writer opens the PR. See the full set of free tools we keep for writers if you want a starting kit.
Format-specific gotchas
Markdown is the easy case. The tooling is mature, every reviewer-side tool can render it, and the syntax surface is small enough that most issues are obvious.
MDX is harder. MDX is Markdown plus React components. The components might be tabs, callouts, accordion sections, embedded code playgrounds. From a reviewer's perspective, MDX is a problem because most rendering tools either ignore the components (showing them as raw <TabGroup> tags) or fail to render them at all. The fix is a renderer that knows about your component library. This is one of the reasons we built DraftView's MDX support the way we did, with NodeViews for known component types so reviewers see a sensible representation of the rendered page.
AsciiDoc is a different kind of harder. The syntax is more powerful than Markdown (include directives, conditionals, attribute substitution, callouts, complex tables) but the tooling is sparser. Most browser-based tools don't render AsciiDoc at all. Most editors don't have great AsciiDoc support. Reviewing an AsciiDoc PR in GitHub's diff view is a special kind of painful because the syntax is unfamiliar to most reviewers, including writers from a Markdown background.
We maintain AsciiDoc Alive, a free in-browser AsciiDoc editor with live preview, Kroki diagrams, MathJax, and GitHub/GitLab import. It's mostly for writing, not review, but it's useful for previewing what an AsciiDoc change will look like before you push. The round-up of free AsciiDoc editors covers the other options in the space.
Frontmatter is the small but real issue. Almost every docs system uses YAML frontmatter at the top of each file for metadata: title, slug, sidebar position, author, date. Reviewers don't want to read frontmatter. Most rendering tools either hide it or render it as a metadata block. Whichever you choose, be consistent.
If you're running a docs site with an “Edit this page” link that points to GitHub's raw editor, your readers and contributors are hitting the diff-view problem too. Our Edit this page integration guide covers how to replace that link with a visual editor so non-developer contributors can actually submit improvements.
Compliance and sign-off
For teams in regulated industries (healthcare, finance, anything with a SOC2 audit ahead of them) the docs review story is also a compliance story. The auditor doesn't just want to see that the change shipped. They want to see who approved it, when, and with what specific feedback.
GitHub gives you most of this natively for engineer reviewers. The reviewer's name is attached to the approval, the comments are in the PR history, the merge is timestamped. For non-engineer reviewers using Google Docs, you have to assemble the audit trail by hand. Pull the Google Doc revision history. Cross-reference the email chain. Hope the reviewer didn't delete their comments. This is fragile.
The fix is the same as the rest of this guide: keep the review where the docs live. Every action the reviewer takes (opening the link, reading the page, leaving a comment, submitting a suggestion) is logged. When the auditor shows up, you have a single source of truth.
For SMEs and legal sign-off specifically, the choke point is usually not the tool. It's that the reviewer needs to formally attest to the change, not just casually comment on it. The SME sign-off guide walks through how to structure the request so the reviewer understands they're being asked for formal approval, what the consequences are, and how the approval is logged.
If you're standing up the docs review process for a team that's going to be audited, build the audit trail into the workflow from day one. Retrofitting it is a tax you don't want to pay.
Anti-patterns to retire
There are a few patterns we see repeatedly in teams that are stuck. Each one feels reasonable from the inside and looks broken from the outside.
The Google Docs round-trip. Writer copies the rendered content into a Google Doc, shares with reviewers, collects feedback, manually applies back to Markdown. Every change goes through two systems. The reviewers like it because Google Docs is familiar. The writers hate it because the reconciliation is slow and error-prone. The longer post on this is The Hidden Cost of Reviewing Docs in Google Docs, but the headline is: every Google Doc review session is 60 to 90 minutes of writer time you're not getting back.
The Confluence mirror. Writer maintains a Markdown version in Git and a Confluence page that mirrors it. Reviewers comment on the Confluence page. Writer copies the changes back to Git. Same problem as the Google Doc roundtrip, with the added wrinkle that Confluence is more expensive to edit and the mirror tends to drift further and faster.
The Slack approval thread. Writer posts “any feedback?” in a Slack channel with a link to the PR. Reviewers send DMs. Writer collects feedback in a private notes doc. Approval is implicit. Audit trail is nonexistent. This works at very small scale and breaks the first time someone asks “who approved this?”
The email PDF redline. Writer exports the doc as a PDF, emails it to reviewers, collects annotated PDFs back, transcribes the annotations into the source. Each reviewer's annotations live in a different file. The writer is now doing both reconciliation and version control by hand. This is the most expensive pattern we've measured.
The single-engineer override. “Just let the docs engineer approve everything.” This isn't review. It's auto-approval with a human in the loop. The docs ship faster but the quality regression is real.
The eternal training. Some team decides the fix is to train all the PMs to use GitHub. They schedule a one-hour onboarding. The PMs sit through it. They forget within a week. The training gets blamed on the PMs. The PMs blame the tool. The training gets repeated. Nothing changes. The fix isn't training. It's tooling that matches how the reviewers already work.
A practical migration path
If you're convinced you have a problem and you want to fix it without disrupting everything, here's the order we'd suggest.
First, measure the current cost. Run your team's numbers through the calculator. Get a baseline. This number is the political capital you need to justify the change. “Our docs review is costing us $X a year” is a sentence that gets attention.
Second, pick one PR to pilot the new flow on. Don't try to switch everything at once. Pick a PR with a mix of engineer and non-engineer reviewers, send it through the new tool, and ask the reviewers afterwards what they thought. Use DraftView's public PR demofor the pilot if you don't want to commit to a tool yet. You can paste in a real PR from your repo and walk reviewers through the experience without signing up for anything.
Third, write down the new workflow. One page. What does the writer do when they open the PR? Who do they assign as reviewers? What does the reviewer get? Where do they leave feedback? When is the PR ready to merge? Boring artifacts like this are the difference between a tool change that sticks and a tool change that gets quietly abandoned.
Fourth, migrate one team at a time. The docs team itself first, then the most enthusiastic adjacent team, then the rest. Don't try a company-wide rollout. They never work for this kind of change.
Fifth, kill the old workflow explicitly. The most common failure mode is that the new workflow gets adopted alongside the old one, instead of replacing it. Writers end up doing both. Make the old workflow's tools (the Google Docs template, the Confluence space, the Slack channel for feedback) explicitly retired. Otherwise people will keep using them out of habit and the cost calculus doesn't change.
For a full walkthrough of how teams have done this migration successfully, the docs-as-code review workflow guide is the most complete piece we've written. If you'd rather just try the tool first, draftview.app/trytakes about 60 seconds. There's also a launch post for the calculator at the cost of docs review drift if you want the executive-summary version of why this matters.
Related reading
A short list of the pieces this guide draws on, all of which go deeper into a single sub-topic.
For the cost problem
For the human side of review
- Why Non-Technical Reviewers Won't Use GitHub
- How to Get SME Sign-Off Without Leaving GitHub
- Sharing Docs PRs With External Reviewers (No GitHub Account)
For workflow and tooling
- Docs-as-Code Review Workflow: A Complete Guide
- Lint Your Docs Before the Pull Request
- Best Free AsciiDoc Editors and Previewers in 2026
- Try DraftView on Any Public GitHub PR
For comparisons against specific tools
- DraftView vs Google Docs
- DraftView vs Confluence
- DraftView vs Notion
- DraftView vs GitHub PR Review
- All comparisons
Free tools you can use right now