THE GITHTML FIELD GUIDE
Use Git blame to locate documentation context, not assign fault
Git blame can identify the recorded revision associated with lines in a document. Use it as a route into history, then inspect the full change and current ownership information. The last person to edit a sentence is not necessarily the subject expert, original author, current maintainer, or person responsible for a defect.
Narrow the inquiry to the confusing lines
Find the smallest passage that raises a concrete question. For example, a timeout recommendation may lack an explanation or conflict with another page. Record the exact path and line range before invoking history tools.
Use git blame -L 40,65 -- docs/retries.html with the appropriate range. The output associates lines with recorded revisions and author information. It does not tell you whether the instruction remains correct for the running system.
Read the associated change
Take the relevant commit identifier and inspect it with git show. A large formatting change may explain why one author appears beside many lines. The meaningful decision may be earlier in history or in a linked discussion.
Look at changes to tests, configuration, and neighboring documentation in the same commit. These can provide useful context, but do not substitute for checking the product’s current behavior. Documentation history records assertions and edits, not execution results.
git blame -L 40,65 -- docs/retries.htmlFind ownership independently
Consult the repository’s ownership conventions, contribution instructions, or team directory to locate the current maintainer. Phrase the question around the instruction: which timeout should this procedure use for version three? Avoid opening with a personal accusation based on a line annotation.
If no owner is documented, ask the repository maintainers to route the question. Record the ownership gap separately. A missing owner can be a maintenance problem without proving that the last editor had any continuing responsibility.
Preserve the useful evidence
Your handoff should include the confusing passage, its source revision, the observed contradiction, and the decision required. Link to a stable snapshot so later edits do not erase the context of the discussion.
When a correction is agreed, update the living guide through the normal review process and explain the operational reason. Keep the historical investigation short and factual. The goal is a clearer instruction for future readers, not an elaborate record of who touched which line.
Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.