THE GITHTML FIELD GUIDE
Prepare an offline incident runbook that states its limits
An offline runbook should help an authorized responder orient themselves when normal documentation is unavailable. Include decision points, prerequisites, expected observations, and escalation information, but clearly identify steps that require live systems. Keep the copy versioned and reviewed; an accessible old command can be more dangerous than a clearly unavailable instruction.
Choose the outage scenario
Define what is unavailable: the public documentation site, the company network, the repository service, or a particular monitoring system. Different outages require different fallback information. A packet designed only for a website outage may still depend on internal links that fail during a wider disruption.
Name the authorized audience and operational scope. An offline reading copy does not grant permission to perform production changes. Keep emergency authority and communication procedures aligned with the organization’s existing incident process.
Include decision context before commands
For each procedure, state the symptom, prerequisites, expected observations, and conditions that require stopping or escalating. Explain which environment and software version the instructions cover. Readers under pressure should not have to infer whether a command applies to their system.
Provide descriptive links for later reference, but include essential warnings locally. If a live dashboard is needed to choose the next step, identify that dependency and the approved fallback rather than substituting a stale screenshot without explanation.
- Define the outage scenario and authorized audience.
- Check version, prerequisites, stop conditions, and escalation details.
- Read the complete packet disconnected on the approved device.
Make the packet genuinely readable
Prefer simple HTML with essential content in the markup, inline CSS, and static explanations for critical diagrams. Include an in-document contents list and clear section headings. Avoid making navigation depend on search services or scripts.
Open the actual copy on the approved device without connectivity. Check escalation information, the final steps of each procedure, and any referenced companion page. For gitHtml, verify the .html documents and required visuals rather than assuming repository assets were mirrored.
Assign a maintenance decision
Name who owns the runbook and what changes require a refresh, such as a new release, an altered escalation route, or a revised recovery procedure. Put the reviewed version and date inside the file.
After an incident, collect documentation failures separately from system failures. Update unclear branches and missing observations through the normal review process. The goal is a trusted fallback for a defined scenario, not a promise that a static file can replace live operational evidence.
Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.