THE GITHTML FIELD GUIDE
Prepare diagrams that remain useful offline
An offline diagram needs both an available visual and a text explanation that carries its meaning. Identify whether the diagram is already an image or generated by a script, then create a permitted static representation when necessary. Do not let the only explanation of a critical relationship depend on a remote renderer.
Identify the diagram’s role
Ask what decision or understanding the figure supports. An architecture diagram might show trust boundaries; a sequence diagram might show which component retries a request. Write that meaning down before choosing an export format.
Classify decorative illustrations separately from essential figures. If losing an image prevents the reader from following the procedure, it belongs in the offline acceptance checklist, not merely in a visual polish review.
Inspect how the visual is produced
A visible diagram may be loaded from an image URL, drawn by JavaScript, embedded as SVG, or displayed inside a remote frame. These have different portability and security characteristics. Inspect the actual output rather than assuming every visible figure is a local image.
For script-generated diagrams, use the tool’s supported static export where available and review the result. Keep the original editable source in its authoring location, but distribute a stable reading representation for the offline task.
- Write the decision or relationship the diagram explains.
- Prepare a permitted static visual and a complete text explanation.
- Check labels and captions in the actual offline copy.
Write the missing explanation
Add a caption naming the diagram’s subject and version context. Then describe its essential relationships in ordinary prose: which component calls which service, what direction data travels, and where the important boundary or exception lies.
Useful alternative text should communicate the image’s purpose without duplicating a long nearby explanation verbatim. Complex figures usually need more than a short image description; give readers a structured explanation in the surrounding document.
Test the figure at reading size
Open the offline copy on the intended device and check labels, contrast, arrow direction, and any legend. Zooming should not be the only way to discover a critical warning. If the figure is too dense, split it into smaller focused views.
For gitHtml, verify the actual figure in the imported HTML environment. Do not assume neighboring image files were automatically saved. If portability is uncertain, include a text-first explanation that remains complete even when the visual cannot load.
Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.