Label Doc Claims By Evidence
label-doc-claims-by-evidence
Summary
Documentation loses trust when speculation, observed behavior, policy, and verified facts look the same. Label claims by their evidence level so readers know what can be relied on and what still needs confirmation.
Problem
Documentation can sound more certain than the evidence behind it. A hunch, a local observation, a benchmark, a contract, and an upstream rule require different reader trust, but prose often presents them with the same confidence.
Preferred Move
Match the claim to the evidence. State contracts as contracts, measurements as measurements, observations as observations, and preferences as preferences. If the evidence is weak, narrow the claim or name the uncertainty. Replace ranking words with the concrete property that earns the claim.
Name the unit of evidence when scope matters: the tested configuration, benchmark environment, changed system, observed path, or quoted decision. A passing combined change does not isolate every constant or branch, and an explanation proposed beside a benchmark is not itself a measured cause.
Tradeoff
Do not turn every sentence into an academic citation exercise. Stable project rules and obvious code facts can be stated directly. Label claims when the difference affects design, review, operations, performance, security, compatibility, or future maintenance.
Agent Instruction
When writing or revising docs, inspect strong words such as `always`, `never`, `guarantees`,
`secure`, `fast`, `safe`, `best`, and `easiest`. Keep them only when the doc points to the
contract, test, measurement, or source that supports them. Name the tested configuration or observed
path when scope matters, and do not attribute the result of a combined change to each part without
isolating evidence.Examples
Bad: the doc overstates a preference as a universal fact.
This layout is always faster and prevents review confusion.
Good: the doc states the evidence and keeps the claim narrow.
In this crate, grouping the parser helpers reduced review churn because reviewers could inspect the
validation path without jumping between modules.
References
| Source | Use | Note |
|---|---|---|
| Google excessive claims | adapts |
Strong claims need enough support for readers. |
| GitHub PR guidance | adapts |
Review context should explain purpose and scope. |