THE GITHTML FIELD GUIDE
Organize repository HTML paths around reader tasks
Organize documentation around what readers need to do, then use stable filenames and a small number of clear entry points. Separate active instructions, reference material, and historical records. A folder structure supports navigation, but the documents still need titles, context, and links that explain which page a reader should open first.
Start with recurring tasks
List the questions that repeatedly bring people to the repository. For a service, these might be setup, configuration, troubleshooting, and architecture. Use those tasks to propose a small directory structure instead of mirroring every internal team or code module.
Keep audience distinctions visible when they matter. A maintainer’s release procedure and an end user’s upgrade guide may share vocabulary but require different permissions and assumptions. Putting them together without labels makes accidental misuse more likely.
Choose durable paths
A workable example is docs/start.html, docs/guides/configure.html, docs/reference/options.html, and docs/history/decision-007.html. The exact names are less important than consistency and a clear entry point. Avoid filenames that encode temporary editorial states such as final-new-fixed.html.
Use a visible version statement inside the page when readers need release context. Paths can remain stable for maintained material, while historical copies receive an explicit archive location and status rather than silently competing with the current guide.
- Group recurring questions by reader task.
- Choose a stable entry page and predictable filenames.
- Verify prerequisites and next-step links from each guide.
Make links part of the structure
Create a short index with a sentence explaining the purpose of each major section. Within a guide, link to its prerequisites and likely next task. A hierarchy that looks tidy in a file browser can still be difficult to navigate as rendered documents.
Check relative destinations from the page’s actual folder. A link that works in a repository web interface may not behave identically in a saved document collection. In gitHtml, verify linked pages separately rather than assuming the entire folder becomes an offline website.
Maintain a small path policy
Write down naming rules, where new pages belong, who approves structural changes, and how old links will be handled. A policy of a few concrete examples is easier to follow than an elaborate taxonomy nobody remembers.
Review the structure when repeated questions reveal a navigation failure. Prefer adding a clearer entry point or cross-link before moving many files. Large reorganizations create link maintenance work and should solve an observed reader problem.
Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.