Drafting Rights: Assign Every Doc Section to a Model or a Named Human
Most documentation pipelines fail on accountability rather than prose quality, because nobody can point at a sentence and name the human who approved it. That gap widens the moment a model drafts pages: reviewers read fluently, approve quickly, and silently inherit claims they never verified. The rule I now apply is narrow enough to enforce in CI — a model may draft anything that describes how…
Most documentation pipelines suffer from a lack of accountability, as nobody can trace a sentence back to the human who approved it. This issue becomes more pronounced when models generate content. To address this, the author now establishes a rule that a model can only draft sections describing the current behavior of the software, while anything promising future functionality is strictly prohibited.
The previous checks focused on numerals, fenced examples, and fact fidelity, but the new approach addresses the question of whether a model was even permitted to write a given sentence.
The documentation is divided into four tiers based on the commitment each sentence demands from the team. Tier 1 includes intros, transitions, glossary wording, and navigation copy, which can be drafted by models with the assurance that they will pass fact gates. Tier 2 consists of mechanism details like build behavior, config keys, CLI flags, and error meanings, where the model drafts but a human verifies the evidence.
Tier 3 covers support windows, deprecation dates, pricing, SLAs, and roadmap wording, which require a named owner to confirm the evidence pointer. Tier 4 comprises security posture, data retention, licensing, and legal terms, where a named owner plus the team shares the risk.
Models are most beneficial in the first two tiers, while the latter two tiers are where most problematic generated documents originate. The distinction between describing current behavior and promising future functionality is crucial. A model that writes "retries are capped at three attempts" is merely describing the code, while a model that writes "we support this until 2028" is inventing a promise.
To ensure adherence to these tiers, the author creates a manifest file, docs-rights.yml, located at the repository root. This file specifies the tier for each section, with defaults applied to unlisted sections. When the manifest changes, it undergoes code review, making any alterations to model rights visible in a diff for potential objections.
The enforcement of these tiers is accomplished through a linter script that parses headings, hashes the normalized section bodies, and compares the hash with a receipt created during the review process. If the reviewed text changes, the receipt becomes outdated, and the check fails until a human revisits the material.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
