Generated Pages Need Owners: A Lane Manifest for API Docs

A release candidate goes out with regenerated endpoint pages. The new prose is easier to scan than the old notes. One added sentence tells clients they can cache a successful response for a day. Another says a 404 means the order was deleted, not that it was missing.

Treat that scene as a composite. It is not a measured incident from this account. The OpenAPI document in the scene says neither sentence. The page is clear anyway. The owner of the two promises is not.

A recent public thread on DEV separated clean code from clear code, and treated comments as a clarity tool rather than a violation (topic signal). The documentation version of that split is stricter. A generated walkthrough can be clear and still unauthorized. This piece is a workflow for that boundary, with a proposed checker. It is not a report of production rates.

The job split

This workflow asks one question before anyone prompts a model. Which sentences may be drafted, and which sentences must be owned by a named person?

Three lanes are enough for an endpoint page. More lanes tend to become a second specification. Keep the split mechanical so a script can enforce it.

Narrative

The narrative lane explains fields and call order using only what the spec already states. A model may draft it. A human reviews it for invented steps. Regeneration is allowed when the spec changes.

Specimen

The specimen lane holds request and response examples. This article does not reopen how fixtures relate to SDK snippets. The boundary is enough. Examples do not live in the narrative file, and a prose pass does not invent them.

Promise

The promise lane is compatibility language. Caching, retry rules, deletion meaning, deprecation windows, and any sentence with "always", "never", "guaranteed", or a time bound belong here. A model must not draft this lane. A named human writes it, dates it, and locks it against regeneration.

A decision matrix

Use the matrix in review. Do not paste it into a prompt and call that a control.

• Field restatement, such as id is a string. Lane: narrative. Keep it only when the spec agrees.
• Sequence help, such as "create the order, then fetch it." Lane: narrative. Reject it when the second call is not in the source.
• Status gloss absent from the spec, such as "404 means deleted." Lane: promise. Drop it, or have a human write a sourced sentence.
• Time bound, such as "cache for 24 hours." Lane: promise. Drop it unless a human owner accepts the number and names the source.
• Sample JSON. Lane: specimen. Do not let a narrative pass invent bodies.

The matrix is a review aid. It is not a measured failure rate. No frequency was collected for this draft.

The ownership manifest

The paths below are a proposed layout. They are not files from a published repository. Dates in the sample are review markers, not evidence that a team signed them.

version: 1
page: endpoints/orders.get
lanes:
  narrative:
    path: docs/orders.get.narrative.md
    regenerate: true
    inputs:
      - openapi/orders.yaml
  specimen:
    path: docs/orders.get.examples.md
    fixture: fixtures/orders/get-200.json
  promise:
    path: docs/orders.get.promise.md
    owner: docs-review
    signed_on: 2026-09-25
    forbid_regen: true
    source: openapi/orders.yaml#/paths/~1orders~1{id}/get

The promise file stays short. Length is not ownership. Policy changes happen by editing this file and moving the date, not by regenerating the page.

<!-- regen:forbidden -->
Owner: docs-review
Signed-on: 2026-09-25
Source: openapi/orders.yaml#/paths/~1orders~1{id}/get

This operation publishes no cache lifetime.
A 404 means no matching order was found. It does not mean the order was deleted.

If product later decides that a 404 does mean deletion, a human edits those two sentences and changes Signed-on. A regeneration job does not get a vote.

The checker

The script is a proposed example. It was not executed for this draft. It needs PyYAML. It does not call a model. It fails when the promise lane is unlocked, or when narrative prose contains a small set of promise-like phrases.

#!/usr/bin/env python3
"""Lane checker for generated API pages. Proposed example; not run for this draft."""

import argparse
import pathlib
import re
import sys

try:
    import yaml
except ImportError:
    sys.exit("PyYAML is required: pip install pyyaml")

PROMISE_HINTS = (
    r"\bsafe to cache\b",
    r"\bguaranteed\b",
    r"\balways returns\b",
    r"\bwill not change\b",
    r"\bbackward[- ]compatible\b",
    r"\bretry until\b",
    r"\bmeans the resource was deleted\b",
    r"\bfor \d+ (?:hours|minutes|days)\b",
)
PROMISE_HEADERS = ("owner:", "signed-on:", "source:")


def main() -> int:
    parser = argparse.ArgumentParser()
    parser.add_argument("--manifest", required=True)
    args = parser.parse_args()
    manifest_path = pathlib.Path(args.manifest)
    data = yaml.safe_load(manifest_path.read_text(encoding="utf-8"))
    lanes = data.get("lanes") if isinstance(data, dict) else None
    if not isinstance(lanes, dict):
        print(f"{manifest_path}: missing lanes")
        return 1

    errors: list[str] = []
    narrative = lanes.get("narrative") or {}
    promise = lanes.get("promise") or {}

    if not promise.get("forbid_regen"):
        errors.append("promise.forbid_regen must be true")
    if not promise.get("owner") or not promise.get("signed_on") or not promise.get("source"):
        errors.append("promise owner, signed_on, and source are required")

    narrative_path = pathlib.Path(narrative.get("path", ""))
    promise_path = pathlib.Path(promise.get("path", ""))
    if not narrative_path.is_file():
        errors.append(f"missing narrative file: {narrative_path}")
    else:
        text = narrative_path.read_text(encoding="utf-8")
        for pattern in PROMISE_HINTS:
            for match in re.finditer(pattern, text, flags=re.IGNORECASE):
                errors.append(
                    f"{narrative_path}: promise-like phrase in narrative: {match.group(0)!r}"
                )

    if not promise_path.is_file():
        errors.append(f"missing promise file: {promise_path}")
    else:
        body = promise_path.read_text(encoding="utf-8")
        lowered = body.lower()
        if "<!-- regen:forbidden -->" not in lowered:
            errors.append(f"{promise_path}: missing regen lock comment")
        for header in PROMISE_HEADERS:
            if header not in lowered:
                errors.append(f"{promise_path}: missing header {header}")

    if errors:
        print("\n".join(errors))
        return 1
    print("lane check passed")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

Run it from the directory that contains docs/. These commands are part of the proposal. They are not a transcript.

python3 -m pip install pyyaml
python3 check_doc_lanes.py --manifest docs/orders.get.lanes.yaml

A useful negative case is a narrative line that says clients may cache the response for 24 hours. The script should exit non-zero and name that phrase. That is the intended behavior of the example, not a captured log. Run it locally before you wire it to CI.

What the model may see

Give the draft pass only the narrative inputs listed in the manifest. Do not attach the promise file as a style sample. Nearby policy sentences get copied.

Keep the prompt boundary dull and specific.

1. Paste the operation from the spec, not the whole repository.
2. Name the output as the narrative path only.
3. Forbid cache lifetimes, retry policy, deletion meaning, and compatibility claims.
4. Ask for no sample JSON in that file.

Then run the checker. A green run means the hint list did not match. It does not mean the prose is free of policy. Read the diff anyway. The read is the control the script cannot be.

Where a free draft host fits

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

The operator states that MonkeyCode offers free model access and a free server option. This draft does not name models, token quotas, hardware, or a time window. Those details were not verified here. Read them from current project documentation before depending on them.

Use that access after the manifest exists, not before. A free model pass may draft the narrative file from the spec excerpt. A free server, if you use the hosted option, is only a place to run the checker so review is not tied to one laptop. Your repository CI remains the merge gate. The host does not own the promise file.

If a hosted draft lane is useful once that gate is in the repo, confirm the free option in the project docs and then try it. Do not add a host in order to invent cache rules or status meanings.

Limitations

Phrase misses

The hint list is short. "Clients can keep the body until the next deploy" will not match safe to cache. Paraphrase is the usual miss. Extend the list from your own incident notes, and still read the narrative file.

Sign-off is not behavior

A signed promise can be false. The date records who accepted the sentence. It does not prove the server behaves that way. Contract tests remain the behavioral check. This script only guards against policy smuggled into a regenerated walkthrough.

Who should skip it

Skip the approach in these cases.

• No named person will accept the promise file. A shared label with no rotation is theater.
• The page is a security, privacy, or legal commitment. That text needs its own review path.
• You want the model to choose product policy. That repeats the opening failure.
• The pipeline assumes a fixed free quota or a permanent runner. Availability can change. Keep the checker in the repo so local CI still runs.

Review order

Follow the same order on each change. Skipping to generation is how promise sentences reappear.

1. Update the spec, or record the human decision the spec does not yet encode.
2. Edit the promise file only if policy changed, and change Signed-on.
3. Regenerate narrative from spec inputs, not from the previous narrative.
4. Run the lane checker.
5. Read every sentence the hints did not catch. Budget that read. Do not replace it with a green script.

Clear generated prose is a drafting result. A compatibility sentence is a decision. The split holds only when those live in different files, with different rights to regenerate.