THE GITHTML FIELD GUIDE
Resolve conflicting sources in an AI documentation draft
When sources disagree, do not ask a generator to blend them into one confident explanation. Identify the conflicting claims, compare their versions and scopes, and ask the responsible owner to resolve the mismatch. Document an interim limitation when necessary, keeping current implementation separate from intended or promised behavior.
Classify the disagreement before deciding
A README may describe an older release, a contract may state intended behavior, and a test may cover only one configuration. These are not automatically contradictory until scope and version match. An illustrative conflict might involve a default timeout described as configurable in a guide but fixed in the inspected code path. Record which environment and entry point each source describes. GitHub's permanent links help preserve this evidence. Avoid declaring that code always wins: code can contain a bug, while a contract can define the behavior maintainers intend to support.
Build a discrepancy record
Use fields for claim A, source A, claim B, source B, shared scope, practical consequence, and owner decision. For the illustrative timeout conflict, explain whether a user following the guide would set an ignored option or merely receive an outdated example. The consequence helps prioritize the review. Ask a narrow question such as whether the option is supported in the target release, rather than requesting a general explanation of the whole subsystem. Keep the generator's proposed reconciliation labeled as a suggestion until evidence or an authorized decision supports it.
- Align revisions, configurations, and interfaces before treating sources as conflicting.
- Explain the user consequence of choosing the wrong interpretation.
- Record the responsible owner's resolution and any required follow-up.
Publish only what the resolution supports
If the conflict is unresolved, narrow the guide to a verified behavior or explicitly state the limitation. Do not silently edit tests, schemas, or implementation as part of reviewing prose. When the owner confirms a correction, update every affected example, summary, and caption, and link the tracked implementation work when relevant. Keep the discrepancy record for future maintainers if it explains historical behavior. A static HTML document should identify the reviewed release so readers understand which resolution it represents rather than assuming it follows every later change automatically.
Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.