Which Documentation Sections Should a Model Draft? A Free-Tier Risk-Split Workflow

The useful question about AI-generated documentation is not whether a model can write it, but which sections a model should be allowed to draft in the first place. A responsibility matrix that separates draft-safe sections from human-owned sections keeps review time low, keeps claims verifiable, and runs entirely on free infrastructure. This article defines that split, provides a small script that enforces it, and marks the boundaries where model drafting should stop even when the tooling is free.

Why whole-set drafting shifts cost sideways

When a model drafts an entire documentation set, the human workload rarely disappears; it simply moves to a review phase that is harder to plan. Reviewers must read prose they never wrote, verify claims they cannot run, and rewrite parts that should have been authored by a human from the first line. The net effect is the same cost, shifted sideways and wrapped in a layer of fluent, plausible text that demands extra suspicion.

The escape from that trap is to decide draft-eligibility before the model runs, not after. Eligibility should rest on two properties: whether a section is a factual extraction from source code, and whether an unverified error in it is cheap or expensive. Both properties are knowable before a single prompt is sent, which makes the matrix a planning tool rather than a post-hoc excuse.

The responsibility matrix

The table below is the core artifact of this workflow. Each row names a documentation section, marks whether a model may draft it, and states who owns the final text. These defaults are deliberately conservative, because a wrong default in a matrix is cheaper to fix than a wrong default in a prompt.

Documentation section	Model may draft	Human must own	Reason
API reference: parameters, return types, errors	Yes	Verify against the source	Factual extraction; a diff is a sufficient check
Installation and setup steps	Yes	Run them once	Environments introduce quirks a model cannot observe
Code examples	Yes, first pass	Execute and correct	An unrun example is a claim, not documentation
Troubleshooting entries	No	Write from real incidents	Failure modes are observed, not invented
Migration guides	No	Write from the changelog and local tests	Breaking changes require judgment about impact
Design rationale and decisions	No	Write entirely	A decision you did not make, you cannot explain
Security-sensitive flows	No	Write and review in person	An error here is an exploit, not a typo

The pattern behind the table is simple: the model may draft anything that can be checked by diffing against source or by running a command, and the human owns anything that requires judgment, incident history, or accountability. The split also solves the ownership problem that plagues generated docs, because every section now has exactly one accountable writer.

A machine-readable ownership file

To make the matrix enforceable, encode it as YAML that sits next to the documentation tree. Each entry declares whether a section is model-draftable and who owns it. Keeping this file in the same repository as the docs means the matrix evolves with the code instead of living in a planning document that drifts.

# docs/ownership.yaml
api-reference:
  model: true
  source: ./src/api.ts
  owner: '@api-maintainer'

installation:
  model: true
  owner: '@release-lead'

examples:
  model: true
  execute: true
  owner: '@docs-lead'

troubleshooting:
  model: false
  owner: '@support-engineer'

migration-guides:
  model: false
  owner: '@maintainers'

security:
  model: false
  owner: '@security-reviewer'

A section missing from this file is treated as human-owned by default, which keeps the safe failure mode simple.

A small verifier for the split

The companion script reads the ownership file and fails whenever a human-owned section contains model output. The model marks its own work with a hidden HTML comment, and the script refuses to continue when that marker appears where it is not allowed. The script below is intentionally minimal, and it runs with Python 3 and PyYAML.

#!/usr/bin/env python3
import pathlib
import sys
import yaml

manifest = yaml.safe_load(pathlib.Path('docs/ownership.yaml').read_text())
marker = '<!--model-drafted-->'
failed = False

for section, rules in manifest.items():
    target = pathlib.Path(f'docs/{section}.md')
    if not target.exists():
        print(f'[missing] {section}', file=sys.stderr)
        failed = True
        continue
    if rules.get('model'):
        print(f'[draftable] {section}')
        continue
    if marker in target.read_text():
        print(f'[blocked] {section} contains model output', file=sys.stderr)
        failed = True
    else:
        print(f'[human-owned] {section} clean')

sys.exit(1 if failed else 0)

For the drafting step, this workflow relies on MonkeyCode's free model access and its free server option, which cover the drafting run without requiring a separate paid runtime (Disclosure: This article was prepared as part of MonkeyCode's product outreach.). The verifier is deliberately model-agnostic: point any drafting service that can emit the marker at this script, and the split survives the tool swap.

Running the pipeline

The full loop is four steps, run in order:

1. Update the ownership file and name a human owner for every section marked model: false.
2. Generate the API reference and setup stubs from the source tree, so the model fills a known skeleton instead of inventing one.
3. Draft the allowed sections with the free server, and instruct the model to end every contribution with the marker.
4. Run the verifier and open a review that lists blocked sections first, because those need human writing rather than human editing.

python3 split_draft.py docs/ownership.yaml
git diff --stat docs/
git add docs/

Run the verifier locally in the pre-commit phase and again in CI when you have it. The gate costs one small Python script, and the benefit is that reviewers stop auditing model prose wholesale and start checking the boundary between drafted facts and owned judgments. The gate stays cheap because it never parses prose; it only looks for a marker in forbidden files.

Limits of this approach and who should not adopt it

This workflow assumes a team that can name an owner for every major documentation section, so it will not help a solo project with no review process or a team that treats docs as an afterthought. Security-sensitive documentation, legal wording, and compliance text should stay out of any model-drafting pipeline regardless of the matrix, because the failure mode is not a bad sentence but an exploited system. Free server options are best-effort infrastructure, so treat the drafting step as a convenience and never as a release dependency. Finally, teams that cannot execute examples in a real environment should mark the examples row as human-owned, because unrun examples are exactly the claims this workflow is designed to catch.

A boundary worth keeping

The value of model-drafted documentation is proportional to the strictness of the boundary around it. A responsibility matrix, a machine-readable ownership file, and a small verifier convert a vague hope about AI writing docs into a checkable process with one accountable human per section. If you want a low-cost environment to test this pattern, the free-tier options described above are a reasonable starting point, and the matrix itself works with any model or runtime you already trust.