Doc Reviews: Let Everyone Edit the Docs, Keep Everything in Git

Most docs never get a second look after they merge. Not because nobody cares, but because the people who'd catch the problems (the PM who knows the feature changed, the lawyer who knows that sentence is a liability, the support lead who answers the same confused ticket every week) have no easy way in.

On GitHub, "fix the docs" means opening a pull request. That's fine for engineers and writers. For everyone else, it's a wall. So the feedback goes somewhere else: a Slack thread, a Google Doc copy, a spreadsheet of "doc issues." Someone then has to carry all of it back into the repository by hand, and half of it gets lost on the way.

We built doc reviews to remove that wall without giving up the thing that makes docs-as-code work: Git stays the source of truth.

Review the docs you already have

Pull request review works when there's a pull request. But a lot of documentation work isn't a change someone already made. It's a page on main that has gone stale, a getting-started guide that needs a fresh pair of eyes before a launch, or a policy page that legal has to check every quarter.

A doc review starts from the files themselves. A maintainer opens the Queue, chooses Add to team queue → Doc review, picks a repository, a branch (main is selected by default), and the files they want reviewed. DraftView gives them a link to share. That's the whole setup. Nobody had to make a branch or an empty commit just to get a review going.

A visual editor anyone can use

When a reviewer opens the link, they see the document rendered the way a reader would see it. Headings look like headings. Tables look like tables. There's no Markdown syntax to learn and no diff view to decode.

From there, they can:

• Comment on any passage, reply to others, and resolve threads, much like comments in Google Docs.
• Edit the text directly. Their changes become suggestions, not overwrites. When they press Save, the edits show up for the rest of the team.
• See everyone else's work. Saved edits from teammates appear in the document text as well as in the side lane, so you're always reading the latest proposed version, not a stale copy.

Reviewers don't need a GitHub account. They join your DraftView organization by email and sign in with a link. A PM, a lawyer, or an outside expert can be reviewing in a minute.

Roles keep this orderly. A commenter can comment. An editor can propose edits. A maintainer decides which edits to accept or reject and when the review is done. Each review can also be capped lower than someone's org role, so you can open a sensitive page for comments only.

Built for reviews that take weeks, not minutes

Real documentation reviews are slow. Legal might take ten days. A subject-matter expert might look at it twice, a week apart. Meanwhile, engineers keep merging to main.

Doc reviews are built for that. When you start a review, DraftView pins every file to the exact commit you started from. Reviewers all work against the same text, no matter what happens on main in the meantime. Nobody gets "this line has changed" errors halfway through a thought.

There's no live co-editing to fight over either. Everyone works on their own edits and saves when they're ready. Each saved edit is an independent proposal. The maintainer's accept or reject is the point where things merge. If two people rewrite the same sentence differently, both proposals sit side by side until someone picks one.

Everything still ends up in Git

This is the part that matters most to the people who own the repository. A doc review doesn't move your documentation somewhere else. It's a temporary workspace that ends in Git.

When a maintainer clicks Finish, DraftView:

1. Applies every accepted edit to the pinned files.
2. Cuts a branch from the commit the review started on and opens one pull request against your branch. Git does the merge against current main, the same way it would for any other branch.
3. Credits GitHub-linked reviewers with Co-authored-by trailers (using their GitHub noreply address, never a private email) and names everyone else in the pull request description.
4. Commits a Markdown review record next to the changes, by default in .draftview/reviews/. It lists every comment, every edit, and every decision, with who made it and when.
5. Posts the comment threads and any edits that didn't make it in as review comments on the pull request, so the discussion is right there when your engineers look at it.

Your normal process takes over from there. CI runs. Branch protection applies. Someone with merge rights merges. Nothing reaches main without going through Git.

If a review produced comments but no accepted edits, it simply completes without a pull request. The comments stay in DraftView, and you can export the record.

A record that holds up

Because every action is logged as it happens, a finished doc review leaves a clear trail: who proposed each change, who accepted it, what the text looked like before and after, and which edits were withdrawn or rejected. You can open that record from the review at any time, and maintainers can export it as Markdown on every plan.

For teams that have to show human oversight of their documentation, especially docs that AI helped write, the Governance plan adds doc reviews to the Oversight report and lets you export a sealed JSON audit record for each review. We wrote more about why that matters in Publicly Accountable AI Writing Needs a Record.

When to use a doc review

Use a pull request review when a change already exists and needs sign-off. That's what DraftView's review queue is for.

Use a doc review when:

• A page on main needs an expert to read it through before a release.
• Legal, compliance, or security needs to check existing wording on a schedule.
• You want feedback from people who will never open a pull request.
• The review will run for days or weeks, and you don't want a long-lived branch going stale.

Try it

Doc reviews are in preview for DraftView organizations. If you've connected the GitHub App, open your Queue, choose Add to team queue → Doc review, pick a few files, and send the link to the people you've been meaning to ask. The edits they make will come back to you as a pull request, and your repository stays the place where the docs live.