Review Cost Per Section Decides Who Drafts It: A Stop Rule for Model-Assisted Docs
Cheaper drafting does not make documentation cheaper; it moves the bill from writing minutes to review minutes. The practical stop rule is therefore economic rather than stylistic: measure what reviewing a section costs relative to writing it by hand, and let that ratio decide which sections a model may draft and which stay human-owned. This post gives the ledger schema, a small runnable script…
Reviewing documentation costs more than just writing time; the real expense lies in the time spent reviewing sections. The practical stop rule for delegating drafting responsibilities is based on the economic ratio of review minutes to hand-written minutes. This post provides a ledger schema, script, unit test, CI gate, and guidelines on when not to adopt the approach.
All numbers in the example fixture are synthetic. Review time is the actual budget when drafting costs nothing; the scarce resource is a reviewer's attention, spent per claim, not per page. A 900-word concept page with two disputed statements may consume more senior time than a 200-word reference stub without disputes, indicating that word count is not a reliable planning metric.
Review minutes per section remain consistent despite tooling changes, as they are derived from artifacts like comments, resolved threads, and factual statement edits. The rule assigns three outcomes: freely drafted, drafted with a checkpoint, or reserved for a human author. Thresholds are starting values for calibration rather than universal constants.
Each reviewable unit should have a single owner and topic, with four key metrics: words (rendered length), review_minutes (review time), blockers (comments changing factual claims), and human_minutes (hand-written time, the anchor for meaningful ratios). The example provided is for the docs/concepts/queue.md page, with four synthetic sections and their respective metrics.
Replace these with actual review timings before applying the rule. The most expensive section to review, "limits," is the shortest and has the most blockers, indicating that short sections about behavior attract tricky claims. To capture the baseline, measure human_minutes once per section by having an engineer write the section on a throwaway branch and record the elapsed time.
This baseline should be updated when subject matter changes to avoid skewed downstream results. Review minutes can be approximated by assigning each comment thread to its respective section and summing the gaps between the first and last human replies. Exclude bot comments and formatting threads, and keep a separate count for threads that change a claim.
If attribution is not possible, place the thread in an unattributed bucket and report it in the output. The Python script, draftcost.py, assigns draft rights per section based on review costs. It uses named constants for thresholds and returns a machine-readable verdict per section plus a page-level ratio. The script is intentionally simple for easy review. The BUDGET_RATIO, FREE_RATIO, CHECKPOINT_RATIO, and BLOCKER_HARD_STOP are adjustable.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
