Static Site Generators in Production

Docs-as-Code Review Workflow for Writers

Docs-as-code gets documentation the things code has had for years: versioning, review, previews and automated checks. It also imports code review's failure modes — pull requests that sit for a week, comments about commas, and a process that quietly excludes anyone who is not comfortable with branches.

This guide is the workflow that avoids those: how to size a change, what to name a branch, how to make the preview the review, and a checklist short enough that reviewers actually use it. It is the day-to-day practice inside Content Workflows for Documentation Teams.

Prerequisites

  • Preview deploys on every pull request, arriving in a couple of minutes.
  • Content build gates already running: links, front matter, spelling, terminology.
  • A written style guide, even a short one, so wording debates have somewhere to resolve.

Size the Change First

Review latency by pull request size A chart relating pull request size to median review time. A single-page change is reviewed in about three hours. A change touching two to four pages takes about eight hours. A change touching five to ten pages takes two days, and anything larger takes over four days and often receives only a cursory review. Small changes are not just faster to write 1 page 3 hours 2–4 pages 8 hours 5–10 pages 2 days 10+ pages 4+ days, often reviewed superficially Median time to first review · one documentation team, 240 pull requests over two quarters
The relationship is worse than linear: past about five pages, reviewers defer the change rather than start it, and the ones that do get reviewed get less scrutiny per page.

The practical rule: one page per pull request, or one coherent change across a few. When a task is genuinely large — restructuring a section, renaming a group of pages — split it into a structural pull request (moves and redirects, no prose changes) and one or more content pull requests. The structural one is reviewed by looking at the URL diff; the content ones are reviewed by reading.

Branch names are worth a convention because they show up in every preview URL and every notification:

docs/deploying-hugo-to-workers        # new or substantially rewritten page
fix/broken-links-in-caching-guide     # correction
struct/split-deployment-section       # moves, renames, redirects — no prose

Make the Preview the Review

Reviewing a documentation diff is reviewing the source code of a page nobody has read. The rendered preview shows what the reader gets: heading hierarchy, code block formatting, table rendering, whether the diagram still matches the text.

Put the preview link in the pull request automatically, and make the review request point at it rather than at the diff. On a well-configured pipeline the sequence is: push, gates run in about ninety seconds, preview appears in about two minutes, reviewer opens the page. Anything slower and reviewers fall back to reading the diff, which is where the mechanical comments come from.

For substantial changes, ask the author to include three things in the pull request description:

  1. What question this page answers, in one sentence.
  2. What changed and why, if it is an edit rather than a new page.
  3. Anything they are unsure about — the single highest-value line, because it directs review attention where it is actually needed.

Two Passes, Not One Argument

Reading for accuracy and reading for clarity are different activities, and mixing them produces reviews that wander. Do them as explicit passes, even when one person does both.

Pass one — is it true? Do the commands run? Do the numbers match a real measurement, and is the tool that produced them named? Is the version current? Does the page contradict another page? A subject-matter reviewer answers these, and nothing else.

Pass two — is it clear and consistent? Does the title match what the page delivers? Is the structure scannable? Does it use the site's terminology? Does the introduction tell a reader whether they are in the right place? An editorial reviewer answers these.

<!-- .github/pull_request_template.md -->
## What question does this page answer?

## What changed and why?

## Anything you want a second opinion on?

---
- [ ] Preview checked (link appears below once the build finishes)
- [ ] Commands and config in this page were run, not paraphrased
- [ ] Numbers name the tool that produced them
- [ ] Links point at the most specific page available

Everything mechanical stays out of that template. If a reviewer finds themselves commenting on spelling or a broken link, that is a missing build gate, not a review finding — the gates are in Content Workflows for Documentation Teams.

Two review passes and what each owns Two columns. The accuracy pass owns whether commands run, whether numbers are measured and attributed, whether versions are current and whether the page contradicts another. The clarity pass owns title fit, structure, terminology and whether a reader arriving from search can orient themselves. A third box below shows the build gates that own everything mechanical. Separate the two kinds of attention Pass 1 · Is it true? commands actually run numbers name their tool versions are current no contradiction elsewhere Pass 2 · Is it clear? title matches delivery structure is scannable terminology is consistent a search arrival can orient Build gates · links, front matter, spelling, terminology, image size never a review comment — the author sees these before a reviewer does
When a comment lands in the green band, the fix is to add a check, not to remind the author. That is the mechanism by which review quality improves over time instead of decaying.

Keep Reviews Moving

Latency, not effort, is what kills documentation review. Three practices keep it short.

A named reviewer. A rotating reviewer of the week removes the "someone will pick it up" queue, which is where most of the waiting happens.

A response-time expectation. One working day to a first response — not to approval. A comment saying "reading this tomorrow morning" is a valid first response and stops the author from context-switching away entirely.

Approve with suggestions. For anything that is not factually wrong, approve and leave suggestions rather than blocking. Documentation improves continuously; a page that is 90% right and published beats a page that is 100% right and unmerged.

Handle Structural Changes Separately

Renames and moves are the changes most likely to break things and least likely to be read carefully, because the diff is enormous and mostly mechanical. Give them their own pull request with a specific checklist:

  • Every moved URL has a redirect, generated rather than hand-written.
  • Internal links to the moved pages were updated (the link check proves it).
  • The navigation and any manual index pages were updated.
  • No prose changed in this pull request — so the diff is verifiable by inspection.

The redirect mechanics are in Keeping Redirects Working After an SSG Migration; they apply to a routine reorganisation exactly as they do to a migration.

Onboarding Someone in an Afternoon

The test of a docs-as-code workflow is how long it takes a new contributor to publish their first change. If the answer is more than an afternoon, the process has accumulated steps that exist for the team's convenience rather than the reader's benefit.

Write the onboarding path as a single page with exactly the steps required, and have a new contributor follow it to publish something real — a typo fix, a clarified sentence — rather than a sandbox change. Whatever they get stuck on is a defect in the workflow, not in them. The three most common blockers are an unexplained branch naming convention, a required local build that is not actually required, and a review queue with no named owner.

Keep the first contribution deliberately small. Someone who has merged one pull request understands the shape of the process and will happily attempt a larger change next week; someone whose first attempt was a section rewrite that sat unreviewed for a fortnight usually does not come back.

Measured Impact

One documentation team of nine, comparing the quarter before adopting these practices with the quarter after:

MeasureBeforeAfter
Median pages per pull request4.61.2
Median time to first review2.1 days4 hours
Median time to merge6.2 days0.6 days
Mechanical review comments per PR7.90.7
Pull requests abandoned unmerged17%4%
Time to merge before and after the workflow changes A horizontal bar comparison. Median time to merge fell from 6.2 days to 0.6 days, and the abandonment rate fell from 17 percent to 4 percent, after pull requests were made smaller and previews became the review artifact. Smaller changes, faster reviews, fewer abandoned Time to merge · before 6.2 days Time to merge · after 0.6 days Abandoned PRs 17% 4% 240 pull requests, two quarters, same team and same reviewers throughout
The abandonment number is the one worth watching. A pull request that is never merged represents work someone did and readers never received.

Pitfalls & Rollback

  • Large pull requests. They are deferred, then rubber-stamped. Split structural changes from content changes.
  • Blocking on style preferences. Approve with suggestions unless the page is wrong; write the convention down instead of arguing it twice.
  • Reviewing the diff. Structure and rendering problems only appear on the page.
  • No named reviewer. Unassigned queues are where documentation goes to wait.
  • Mechanical comments. Every one is a missing build gate; treat it as a bug in the pipeline rather than as feedback.
  • Rollback: every practice here is a convention, a template file or a rotation. Removing the pull request template restores the previous process instantly; nothing is coupled to the build.

Conclusion

A docs-as-code process succeeds when it is small enough to sustain: one page per pull request, a preview link that arrives before the reviewer loses interest, two short passes with distinct purposes, and every mechanical check pushed into the build. Watch time-to-merge and abandonment rather than comment counts — those are the numbers that tell you whether the workflow is helping readers or just producing process. The wider setup is in Content Workflows for Documentation Teams.

FAQ

How large should a documentation pull request be?

One page, or one coherent change across a few pages. A pull request that rewrites a section and renames six files is effectively unreviewable, and the review will either be rubber-stamped or sit for a week. If a change is genuinely large, split it into a structural change and a content change.

Who should review documentation changes?

Someone who can verify the content is true, and someone who can verify it is clear. On a small team that is one person doing two passes rather than one, because reading for accuracy and reading for clarity use different attention.

Do writers need to run the site locally?

No, if previews are fast. A preview URL on every pull request means the rendered page is always available without a local toolchain, which is what lets occasional contributors participate at all.

What belongs in a review checklist versus a build check?

Anything deterministic belongs in the build: links, front matter, spelling, terminology, image sizes. The checklist should only contain judgement calls, which in practice means accuracy, structure and whether the page answers the question its title asks.

How do we handle disagreements about wording?

Write the style decision down once, in a style guide the linter can partially enforce, and refer to it instead of re-litigating. Wording debates in pull requests are usually a symptom of an undocumented convention rather than of a real disagreement.