THE GITHTML FIELD GUIDE
Record provenance inside an HTML documentation copy
Put a compact provenance block inside every important HTML export: document title, source repository and path, source revision, export date, and intended product version. This lets readers distinguish a current guide from a historical snapshot even when the file is forwarded, renamed, or separated from the message that originally explained it.
Separate source identity from export time
The source revision identifies the recorded content used to create the copy. The export date identifies when the conversion or packaging occurred. Those dates can differ substantially, and neither alone establishes that the guide is current for a deployed system.
Include both when the distinction matters. A newly exported manual can still describe an old release. Avoid a large updated today label that accidentally implies the underlying technical instructions were reviewed today.
Capture the minimum useful record
A practical block contains title, source path, commit identifier, target product version, export tool, and review status. For example, a release handbook might say that it was built from a named commit for version 2.4 and checked for offline reading on a stated date.
Do not fill unknown fields with guesses. Write not recorded or not verified when necessary. An honest incomplete record is better than a polished provenance table that gives false confidence.
- Record source path, revision, target version, and export date.
- Label content review and offline checks independently.
- Verify provenance against the final distributed HTML.
Link back without making the link essential
Use a permanent GitHub file link for the source snapshot where appropriate. Include a separate maintained-guide link if readers may need current instructions later. Give each link a label explaining its role rather than displaying two indistinguishable source buttons.
The document must remain understandable without opening either destination. Private links still require permission, and offline readers cannot retrieve remote context on demand. Put critical prerequisites and status information in the copy itself.
Check the block during every refresh
When replacing a reading copy, update the source revision and export details together. Verify that the title and version in the main text agree with the provenance block. Mixed metadata is a common sign that the wrong file was distributed.
Keep review claims narrow: content reviewed, links checked, and offline reading checked are separate statements. Do not claim a complete operational test merely because the HTML opens. The block should explain what is known, not serve as a decorative seal of approval.
Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.