THE GITHTML FIELD GUIDE
Build an evidence ledger for AI-generated documentation
An evidence ledger connects each important generated claim to the source that supports it. Record the claim, source location, revision, evidence type, and review outcome. Mark unsupported statements for correction or removal, and distinguish a source that merely mentions a topic from one that actually establishes the claimed behavior.
Choose claims that deserve individual review
Not every connecting sentence needs its own row, but behavioral guarantees, limits, permissions, and data handling do. An illustrative claim that failed imports are retried automatically needs evidence of the retry path and its conditions. A function named retryImport is not enough if the documentation describes an unconditional guarantee. NIST's generative AI profile identifies confidently incorrect output as a risk; the ledger is an editorial technique for making such mistakes visible. Keep the review focused on the statements that would change a reader's decisions.
Create a compact ledger entry
For each claim, write the exact proposition, a stable source link, the relevant symbol or configuration, what the evidence shows, what it does not show, and the reviewer decision. An illustrative entry might conclude that retries exist for transient network failures but not for invalid input. The corrected documentation should preserve that condition. GitHub's permanent file links help keep evidence tied to a particular revision instead of a moving branch. Do not manufacture a source location because the model's suggested line number looks plausible.
- Claim: express one behavior that can be checked independently.
- Evidence: identify the revision and the condition demonstrated by the source.
- Decision: accept, qualify, remove, or ask the responsible maintainer.
Use the ledger to revise the document
Review the highest-consequence claims first, then propagate corrections into summaries, diagrams, captions, and examples. A qualified sentence in the body does not fix an overconfident title. Retain unresolved rows when publishing is blocked rather than silently dropping inconvenient questions. Keep the ledger accessible to maintainers, with sensitive source material restricted appropriately. If you export the approved guide to HTML, include a short scope and revision note. The ledger establishes what was reviewed at that time; it does not certify future revisions or substitute for testing.
Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.