# Doc Previews an SME Can Review Before the Merge

Canonical: https://commareports.com/for/technical-writers
Published: 2026-09-11

> Your reviewer won't check out a branch to read a MkDocs build, so they review the rendered site after it ships. Publish the preview to a link and collect anchored comments on the paragraph.

# Reviews that happen before the merge

Docs review has a structural problem: the people whose approval matters —
the engineer who built the feature, the support lead who will field the
tickets, the PM who named it — will not check out a branch and run
`mkdocs serve`. So they review the published site, after it ships, by sending
you a list of corrections.

The fix isn't process. It's giving them a URL.

## Publish the build, per branch

Add a step to the docs pipeline that publishes the built site and updates the
**same report** each push, so the preview link in the PR description is always
current:

```bash
mkdocs build
curl -fsS -X PATCH "https://commareports.com/api/v1/reports/$DOCS_PREVIEW_ID" \
  -H "Authorization: Bearer $COMMA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d @site.json
```

Publish the **whole output folder** — docs sites are the clearest case for it,
since cross-page links, the search index, the stylesheet and the fonts all
live beside the entry file. See [share an HTML folder](/share-html-folder).

Per-generator detail:
[MkDocs](/share-mkdocs-site) · [Sphinx](/share-sphinx-docs) ·
[Docusaurus](/share-docusaurus-site) · [VitePress](/share-vitepress-site) ·
[Antora](/share-antora-docs) · [mdBook](/share-mdbook) ·
[Jupyter Book](/share-jupyter-book) · [Bookdown](/share-bookdown-book) ·
[Quarto](/share-quarto-report) · [Hugo](/share-hugo-site) ·
[Jekyll](/share-jekyll-site) · [Eleventy](/share-eleventy-site) ·
[AsciiDoc](/share-asciidoc-html) · [Pandoc](/share-pandoc-html).

API reference builds:
[OpenAPI](/share-openapi-docs) · [Redoc](/share-redoc-api-docs) ·
[Swagger UI](/share-swagger-ui-docs) · [Javadoc](/share-javadoc) ·
[JSDoc](/share-jsdoc) · [TypeDoc](/share-typedoc) ·
[rustdoc](/share-rustdoc) · [Doxygen](/share-doxygen-docs) ·
[Dokka](/share-dokka-docs) · [phpDocumentor](/share-phpdoc) ·
[YARD](/share-yard-docs) · [pkgdown](/share-pkgdown-site).

## Anchored comments are the whole point

A reviewer's most valuable contribution is a correction attached to a
sentence: _"this flag was removed in 3.2"_, _"this order is wrong, you have to
authenticate first"_, _"nobody calls it that internally"_.

Sent as an email, that becomes a scavenger hunt. Left as an anchored comment,
it's a queue you work through with the text in front of you. See
[commenting on HTML](/comment-on-html).

Reviewers need no account, no editor, no local toolchain, and they are never
billed — which is what makes it realistic to ask three SMEs instead of one.

## Revisions are the review round

Each redraft is a revision at the same URL. The PR link doesn't change, the
reviewer refreshes, and the history shows what moved between rounds — useful
when someone asks whether their week-one comment was ever addressed.

If a docs agent is drafting, it can read the open threads and revise against
them directly — see
[letting an agent respond to comments](/agents/let-an-agent-respond-to-comments).

## Worth knowing

- **Start private.** Unreleased feature docs are an embargo problem before
  they're a review problem — see [sharing & access control](/docs/sharing).
- **Search behaviour.** Bundled client-side search (MkDocs Material,
  Docusaurus, VitePress) works. Hosted search that calls an external service
  depends on that service's origin rules.
- **Limits.** Entry HTML 5 MB; assets 25 MB per file, 250 MB and 500 files per
  report. A large API reference with per-symbol pages is the usual file-count
  offender — publish the section under review rather than the entire build.
- **Keep the real docs site.** This is a review surface, not a replacement for
  publishing.

## Try it

Comma is free — unlimited reports, unlimited commenters, unlimited revision
history.

**[Start free →](/login)**

### Related

- [For open-source maintainers](/for/open-source-maintainers) ·
  [For engineering managers](/for/engineering-managers)
- [Read the Docs alternatives](/alternatives/read-the-docs-alternatives) ·
  [GitHub Pages alternatives](/alternatives/github-pages-alternatives)
- [Publish reports from CI](/ci) · [Comment on HTML](/comment-on-html)