THE GITHTML FIELD GUIDE
Label historical documentation so readers do not mistake it for current guidance
Keep historical documents readable, but label their time period and status at the beginning. Distinguish an archived decision from an obsolete procedure and point readers toward maintained guidance when it exists. A historical file can remain valuable evidence without being a safe instruction for the current system or release.
Decide what is being preserved
An architecture decision explains why a choice was made; an old installation manual explains how a past release worked. These are different archival purposes. State the purpose before deciding whether to keep, relocate, or summarize the document.
Record the supported product version or relevant date range. Avoid vague labels such as old or legacy when you can name the exact release. A reader investigating an incident needs precise chronology, not merely a warning that the page is dusty.
Put the status before the procedure
Add an introductory notice that identifies the document as historical and explains whether its steps should still be followed. If there is a replacement, link to it with a descriptive label. Do not hide the status in a footer after a long command sequence.
For example, an archive notice can say that the guide describes release two and is retained for investigation, while new installations should use the maintained setup guide. Keep this message distinct from the original historical text.
- State the preserved release and archival purpose.
- Put historical status before any operational instructions.
- Link the maintained replacement and exact historical source separately.
Retain reliable provenance
Use a commit-specific source link when citing the preserved version. Note whether the archive is an exact copy or a later explanatory edition. If annotations are added, label them so readers do not attribute modern commentary to the original authors.
A branch-based URL may lead to different content later. Pair a maintained replacement link with an immutable historical reference when both current action and past evidence matter to the reader.
Keep archives out of the default task route
Make active guides the primary navigation destinations and place historical material in a clearly named section. Search results and indexes should include the status in their visible description where your publishing system supports it.
Review archived pages for sensitive material before distributing copies. Historical status does not remove confidentiality obligations. For a portable HTML archive, include title, source revision, date context, and replacement information inside the file so those details survive separation from the original repository folder.
Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.