THE GITHTML FIELD GUIDE
Label uncertainty in AI-generated documentation without losing usefulness
Useful uncertainty labels explain what is known, what is inferred, and what remains unknown. Apply them to specific claims, not to the whole document with a blanket disclaimer. Preserve the evidence and the next verification step so readers can still act appropriately without mistaking a plausible explanation for established behavior.
Distinguish absence of evidence from evidence of absence
If a reviewed excerpt contains no retry logic, it does not prove that the entire system never retries. The behavior might live in a caller, a queue, or infrastructure outside the inspected scope. An illustrative statement should say that no retry was observed in the reviewed function and name the remaining boundary. NIST's generative AI profile discusses incorrect generated content; uncertainty handling is one way to avoid converting incomplete context into an unqualified assertion. Do not assign a numeric confidence score unless it comes from a meaningful, explained method.
Use a claim-level vocabulary
A practical editorial scheme uses observed, inferred, and unknown. Observed means the cited evidence directly supports the statement. Inferred means the evidence suggests an explanation but leaves a stated gap. Unknown means the review cannot establish the behavior. An illustrative entry might say: Observed: the handler returns a pending status after enqueueing. Unknown: the maximum delay before a worker starts, because scheduling configuration was not provided. This is more helpful than probably asynchronous, which combines an imprecise claim with an unexplained degree of certainty.
- State the claim and its scope in one sentence.
- Name the evidence and the exact missing link.
- Identify who or what could resolve the remaining question.
Keep caveats attached to the conclusion
When shortening the document, preserve conditions that change the meaning of a claim. A summary that says exports always succeed is not repaired by a limitation buried later. Ask a maintainer whether the unknown blocks publication, requires a warning, or simply limits the page's scope. Remove filler hedging when the source is clear; uncertainty should not make every sentence evasive. In HTML, use plain labels and explanatory text instead of relying only on colored badges. Readers should understand the confidence boundary with or without decorative styling.
Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.