From Linting to Sign-off: A Complete Docs-as-Code Review Workflow

Linting your documentation is the right first step. It catches style violations, enforces terminology consistency, and makes sure your content meets the bar before anyone else has to look at it. But linting is only half the problem.

The other half is getting the content reviewed by the people who matter: subject matter experts, product managers, legal, support leads, or any stakeholder who needs to sign off before a docs change goes live. And in docs-as-code workflows, that second half routinely breaks down.

The reason is almost always the same: your reviewers don't use GitHub.

This post covers a complete workflow that solves both problems. ProseLint Web for browser-based linting before you submit. DraftView for stakeholder review after you do.

Why docs-as-code review is harder than it looks

Docs-as-code is a well-established practice: write documentation in Markdown, AsciiDoc, or MDX, store it in a Git repository, and manage changes through pull requests. Technical writers and engineers love it because it brings software development discipline to documentation work.

The problem surfaces when you need review from non-technical stakeholders.

GitHub is a barrier for non-technical reviewers. A product manager, legal counsel, or support lead reviewing a pull request has to create a GitHub account, understand diff views, figure out how to leave inline comments, and navigate a UI designed for engineers. Many simply refuse, and the review step gets skipped or moved to a separate document, breaking the single-source-of-truth model that makes docs-as-code worthwhile.

Copy-paste review workflows are fragile. Teams often resort to exporting content to Google Docs or Confluence for stakeholder review, then manually reconciling changes back into the source files. This creates version drift, loses comment history, and doubles the work for writers.

Review quality suffers when the process is painful. When reviewers find the tool hard to use, they disengage early. You get cursory approvals instead of real feedback, and content quality suffers as a result.

A good workflow solves this at the tooling level, not by asking reviewers to learn new systems.

Step one: lint before you open a PR

The pre-review step is where ProseLint Web fits. Before you open a pull request, before any human reviewer spends time on your content, run it through the linter.

This matters because every style issue, terminology inconsistency, or passive voice problem that a tool can catch is one less thing your reviewers need to flag. Reviewer time is expensive. Using it on "you said 'click' but the style guide requires 'select'" is wasteful. Save their attention for content structure, technical accuracy, and the judgment calls that only a human can make.

What to lint

Run linting on every file you touched. If your change affects shared terminology or cross-referenced content, lint the broader docs directory.

ProseLint Web supports:

Markdown (.md)
MDX (.mdx)
AsciiDoc (.adoc, .asciidoc)
HTML and plain text

This means the same browser tool covers most docs-as-code stacks without configuration.

Which style guide to use

Choose the package that matches your team's standards. The most widely used options in the ProseLint Web editor:

Microsoft Writing Style Guide: The default choice for most technical documentation. Conservative, thorough, and well-understood across the industry.

Google Developer Documentation Style Guide: A better fit for developer-facing content, API documentation, and tutorials aimed at engineers.

Red Hat Documentation Style Guide: Strong for open-source software and infrastructure documentation.

If your team uses a consistent style guide in CI, use the same one locally. Consistency between your local check and the CI check is the point: no surprises when the PR lands.

The pre-PR checklist

Before opening your pull request:

Open ProseLint Web and paste or upload the files you changed
Select your team's style guide package
Work through errors first, then warnings
For intentional exceptions (passive voice in an API reference description, a specific product name that triggers a rule), note them in your PR description
Re-run until the issue count is zero or all remaining items are documented exceptions

This takes five to ten minutes for most changes. The time investment pays back immediately in cleaner review cycles.

Step two: get it reviewed without GitHub friction

Once your content is linted and the PR is open, the review step begins. For internal technical review (other writers, engineers), GitHub's native review tools work fine. The problem is external or non-technical stakeholders.

This is where DraftView fits.

DraftView is a GitHub-native review tool built specifically for this scenario. It connects to your repository and pull request, renders the documentation as readable prose rather than a code diff, and lets reviewers leave inline comments and approve changes, all without needing a GitHub account.

How it works

The writer connects DraftView to the PR
DraftView generates a review link with a rendered, readable view of the changed content
The writer shares that link with stakeholders
Stakeholders open the link in a browser, read the content as formatted documentation, and leave comments
Comments flow back into the PR as GitHub review comments
The writer addresses feedback, and the PR is approved through normal GitHub workflow

The reviewer experience is a clean reading view with inline commenting, closer to reviewing a document than reviewing code. No GitHub account, no diff views, no learning curve.

Who this is for

Subject matter experts: Engineers, scientists, or product specialists who need to verify technical accuracy but don't work in GitHub day-to-day.

Legal and compliance: Teams reviewing documentation for regulatory accuracy, brand compliance, or terms of service implications.

Product managers: Stakeholders who own the product area and need to sign off on how features are described to users.

Support and success teams: Customer-facing teams who review documentation for clarity and completeness before it goes live.

External contributors: Open-source projects where some reviewers are community members without repository access.

Any person who needs to review documentation content but shouldn't need to learn GitHub to do it.

The complete workflow

Putting both tools together:

Writing phase

Draft your documentation changes in your local editor
Follow your team's style guide as you write. Linting catches what slips through, not everything.

Pre-PR linting phase

Open ProseLint Web and load your changed files
Select your team's style guide package
Fix all errors; review and document exceptions for warnings
Commit clean files to your branch

PR and technical review phase

Open the pull request on GitHub
Internal technical review happens through normal GitHub review (engineers, other writers)
Address technical feedback and push updates

Stakeholder review phase

Connect DraftView to the PR and generate a review link
Share the link with subject matter experts, product managers, or legal
Reviewers read rendered documentation and leave inline comments
Address stakeholder feedback and push updates
Stakeholders confirm via DraftView; approval reflects in the PR

Merge phase

PR meets all approval requirements
Merge through your normal branch strategy
Documentation is live

This workflow keeps everything in one source of truth (the pull request) while removing the GitHub barrier for non-technical stakeholders. No copy-pasting to Google Docs, no email threads, no version reconciliation.

Why the order matters

Lint before review, not after. This sounds obvious but teams frequently get it backwards: they open the PR first, then discover style issues during review.

When style issues appear in review, two things happen that waste time:

Reviewers lose focus. A subject matter expert who notices "click" vs "select" inconsistencies stops thinking about content accuracy and starts catching style errors. Their valuable domain expertise gets spent on mechanical issues that a tool should have caught.

Review cycles multiply. Every round of feedback that includes both style fixes and content changes requires another review pass. Keeping style fixes and content changes separate (linting handles style, reviewers handle content) keeps review cycles to a minimum.

Lint first, then get the right people to review the right things.

Integrating with CI

ProseLint Web handles the individual pre-PR check. For teams who want automated enforcement at the CI level, add Vale CLI to your pipeline to catch anything that slips through:

# .github/workflows/vale.yml
name: Lint documentation

on: [pull_request]

jobs:
  vale:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: errata-ai/vale-action@v2
        with:
          files: docs
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

This creates two layers of linting:

Local: ProseLint Web in the browser, fast feedback during writing
Automated: Vale CLI in CI, enforces consistency on every PR regardless of whether the writer ran local checks

Both layers use the same rule packages, so the results are consistent.

Summary

The docs-as-code review problem has two parts. Style and consistency is what linting solves, and ProseLint Web makes it available in the browser without installation or configuration. Stakeholder sign-off is what breaks down when reviewers don't have GitHub accounts, and DraftView solves it by decoupling the review experience from GitHub while keeping the PR as the source of truth.

Neither tool replaces the other. They address different parts of the same workflow: write clean content, then get the right people to review it.

Resources

ProseLint Web editor: browser-based Vale linting, no install required
DraftView: stakeholder PR review without GitHub accounts
Vale CLI: open-source prose linting for CI/CD integration
Vale packages repository: professional style guides from Microsoft, Google, Red Hat, and more
Vale GitHub Action: automated linting in GitHub Actions