Docs as Code Workflow Template
A contribution guide, a review procedure, and the ledger that says how much of last quarter's review a linter rule could have made.
Free download · No account needed
Review Effort Note
[Quarter], [repository]
The quarter, in five counts
| Documentation pull requests | — |
| Review rounds across them | — |
| Review comments | — |
| Review requests sent | — |
| Entries in the house style guide | — |
What could have caught each comment instead
| A linter rule | — |
| The rendered page, which a diff is not | — |
| Nothing except that reviewer | — |
The finding this note exists to produce
Three counts, never one. A falling total is equally consistent with reviewers giving up, so the signal is the first count falling while the third holds. Each label routes somewhere different: a rule to write, a reviewer sent the wrong artifact, or a review doing its job.
The rules behind the first count
Every style guide entry those comments hit, ordered by comments drawn, with the linter state on each: installed and blocking, installed at suggestion severity, scoped away by a path exclusion, or never installed.
Who was asked, and who looked
Requests, answers, approvals with nothing attached, and substantive comments per engaged review, split by whether the reviewer works in the repository. The last column is the one that reverses the obvious conclusion.
What it cost
Minutes to write a comment plus minutes to address one, times the first count. Then the review rounds that carried nothing a build could not have refused, and the median days to merge with and without an outside reviewer.
The three actions
Config lines first, then the single rule worth writing next, then the reviewer group to move onto a preview URL.
Docs as code puts documentation through the same review as source, which makes the pull request the entire quality gate. Wrenfield Analytics runs 277 pages that way. Last quarter it merged 142 documentation pull requests across 440 review rounds and drew 1,186 review comments. Labelled by what could have caught each one instead: 512 a linter rule could have made, 291 that only the rendered page shows, 383 that needed that reviewer. The third number is the only one a review is for.
The 291 explain the second count. 143 review requests went to people outside the repository, and 28 came back with a comment. GitHub attaches a review comment to a line in the diff, so a support lead asked to check an instruction has to render Markdown in their head first. Most decline by approving. Yet those 28 reviews carried 4.1 substantive comments each against 1.7 from the reviewers who live in the repository. They were not disengaged. They were sent the wrong artifact.
The 512 trace to 43 style guide entries: 31 never installed, and 12 installed and let through anyway by a suggestion severity or an excluded path. Of 96 entries, 79 are mechanically checkable and 19 have a rule today, which is what prose linting exists to close. At 5.5 minutes of two people's time per comment that is 47 hours a quarter and 118 whole review rounds spent on what a build should refuse. A documentation audit finds the same class of error a year later, for forty times the money.
What's in the pack
Review Comment Ledger
One row per pull request, splitting its comments into what a rule could have caught, what only the rendered page shows, and what needed the reviewer.
Style Rule Register
Every style guide entry against the linter config, ordered by the review comments it drew, so the top row is the rule worth writing next.
Review SLA Tracker
Response rate per group next to substantive comments per engaged review, which is the pairing that tells a routing problem from a disengaged reviewer.
Ownership Register
One named human per doc area and the reviewer group a change there requires, with at most two of them set as blocking code owners.
Toolchain Register
What each tool actually stops, which is usually less than its name suggests: the scope, whether it blocks a merge, and how many style entries it enforces.
Contribution Guide
Three routes in, chosen by whether the contributor works in the repository, and the named question every review request has to carry.
Review Procedure
What each reviewer is sent and what happens when they do not answer, including the rule that an approval with nothing attached is not a technical review.
Style Guide
Only the entries a machine cannot check, as five questions, so it stays short enough to read twice. Scoring the entries you already have is the copyedit and style pack.
Review Effort Note
The worked quarter: the three counts, the rule families behind them, the hours, and the three actions they produce, cheapest first.
How it works
- 1
Open or download
Edit with AI installs the pack as a private Space and asks for a quarter of documentation pull requests, your style guide, and your current linter config. Download gives you the blank files, no account.
- 2
Label every comment
Each review comment gets one label: a rule could have caught it, only the rendered page shows it, or only the reviewer knew it. The labels are exclusive and each one routes to a different fix.
- 3
Join the guide to the config
Every style guide entry is classed as machine-checkable or not, then checked against the linter as it actually runs. Installed and blocking, warning only, scoped away, or absent are four different answers.
- 4
Route the reviewers and cost it
Reviewers who work in the repository keep getting diffs. Everyone else gets a preview URL and one named question, with a clock. The hours the first label cost is the number that changes the config.
Frequently asked questions
What does it need from me?
A quarter of documentation pull requests with their review comments, or the twenty most recent if you cannot export. Your style guide in whatever form it exists, including one person's memory. Your linter config as it runs today, exclusions included. And who a change is required to be reviewed by.
What format are the downloaded files?
Four Word documents and five CSV sheets, zipped. The documents open in Word, Pages and Google Docs; the sheets open in Excel, Numbers and Sheets. Nothing needs converting. Add a PDF query string to the download if you want to circulate the procedure rather than fill it in.
What does Edit with AI actually do?
It installs this pack as a private Space, then runs the pass that costs the most by hand: labelling every review comment and mapping the lintable ones onto the style guide entries they hit. You get the register ordered by comments drawn, with the config-only fixes at the top.
Does it write our linter rules?
It tells you which rule to write next and what that rule has drawn in review comments, and it separates the entries needing a rule from the entries whose rule already exists and is misconfigured. The second group is usually a third of the list and each one is a config line.
Our reviewers ignore documentation pull requests. Does this help?
It first checks whether that is true. Response rate alone cannot tell a disengaged group from a group being handed a diff it cannot read, so the tracker puts the rate next to substantive comments per engaged review. When the second number is high, the fix is routing, not reminders.
How is this different from auditing the published pages?
This works on changes while the diff is open, so nothing has shipped yet. Checking pages after the fact is the documentation audit, mapping a release to the pages it invalidates is the release notes pack, and checking a reference against the real API surface is the OpenAPI gap workup. Where a page belongs in the nav is the information architecture pack.
Is any of this free?
The download is free and needs no account: the real documents and sheets, blank, as Word and CSV. Edit with AI creates a free account and fills them in from your own pull requests. The pack in the zip is the same pack the AI works from, not a trimmed sample.
Find out what your reviews were actually spent on
Download the blank Review Comment Ledger, Style Rule Register and Review SLA Tracker as Word and CSV, or have River label a quarter of your own pull requests.
Edit with AI