LEARN. PRACTICE. GROW.Define the decision the document supports
A runbook should let someone decide and perform an action under the intended conditions. Start with service, version, audience and operation: restarting one instance is not recovering an application or reconciling batch files. For a fictional fund-reporting service, identify the closing window, input data and person confirming functional recovery. Record preconditions, expected outcome, boundaries and contacts. The project manager can require these elements at operational handover while a specialist validates commands and dependencies. A lengthy page without success criteria still leaves decisions unresolved. Use a rehearsal to find steps the author knows from memory but on-call staff cannot infer from the text. Ask the receiving operator to explain the stop conditions before attempting the procedure, so uncertainty becomes visible while support is available.
Choose the source and control review
When documentation follows software changes, a code wiki lets Markdown files stay in the repository and use review on the published branch. The mapping identifies repository, branch and folder. A change in main:/docs does not update a wiki reading release/4:/ops. Before diagnosing cache, compare those three elements and look for the commit in the actual published path. To require prior review, configure branch policies and check compliance; a pull request link does not establish approval. In the exercise, the correction must be adapted to version 4 before integration. Blindly copying version 5 instructions may introduce configuration options the older binary cannot recognize. Include the reviewer’s technical reasoning in the change rather than relying only on the branch name.
Ensure access for the right audience
Test reading with an authorized identity representing RUN. The author may have Basic and contribution permissions while on-call staff have a different access level. In private projects, Stakeholder does not provide access to a published code wiki; repository permissions do not replace that limit. There is also no per-page permission boundary within the same wiki. If some instructions have a restricted audience, separate them into a repository or system with suitable access control. Removing an index entry does not protect content. At handover, record who can open the required revision and how authorized contingency access works. Any alternative must respect document classification without distributing credentials or increasing write permissions merely to solve a reading problem. Repeat the check when team membership changes.
Navigation and diagrams that help action
Navigation should bring the operator closer to the applicable procedure. Check names, case, links and page order; an outdated index may send a reader to an old recovery procedure. In.order, the entry uses the page name without.md and with matching case. For diagrams, distinguish syntactic validity from operational validity. A diagram can render a wrong process perfectly. The example shows restart followed by Process running and incident closure, but the internal rule requires functional confirmation. Add the check and both success and failure paths. The wiki has its own Mermaid limits: use documented target syntax and check rendering rather than assume another editor uses the same version or capabilities. Have an operator walk through both branches to expose missing actions.
Fix the version applicable to delivery
A branch is a reference that can advance. The main URL may be useful for current documentation but does not by itself identify the approved procedure for an earlier release. In the handover package, link the delivered version to the exact runbook revision and review evidence. Preserve scope too: a correct document for the wrong application does not satisfy the need. The fictional example uses release 4, revision doc-r4 and a recovery rehearsal with RUN. If an emergency change modifies configuration, reassess affected instructions before reusing earlier approval. This linkage is a governance convention for the exercise, not an automatic feature guaranteed merely because the file is in Git. Retain the reason for choosing the revision alongside the identifier.
Diagnose the notification chain
A notification depends on an event, a subscription selecting it and a delivery method for the chosen audience. If Ana receives notices for main but not release/4, start by comparing the filter and personal scope with the team requirement. There is no reason to alter transport first when selection already excludes the event. For service hooks, also check access to source resources: managing subscriptions does not grant read access to a restricted area. Distinguish this situation from an HTTP attempt that failed at the destination. Record the event identifier, relevant subscription and stage where evidence is missing. This supports escalation to the right team without inventing that the whole chain worked simply because a subscription exists. Test a matching and a deliberately nonmatching event when validating filters.
Confirm recipients and responsibilities
A team subscription name does not mean everyone receives every event. Role-based delivery may select only the current assignee, while another option sends individually to members. Confirm the intended audience before widening distribution and assess whether event details may be shared with that audience. A technical message also needs enough context for the next action: service, observed impact, change reference and link to the applicable procedure. The team should know who takes ownership and when to escalate. In an international context, use explicit instants and avoid phrases such as tomorrow night without a time zone. This exercise imposes no universal SLA; acknowledgement time and escalation depend on the internal agreement and service criticality. Validate recipient selection with the actual receiving team.
Accept handover with evidence
Complete handover with a small set of demonstrations rather than a page count. In the fund-reporting case, RUN opens the approved release 4 revision, interprets the procedure and performs a representative rehearsal in an authorized environment. The team records outcome, known constraints and outstanding actions. The manager decides readiness against the agreed criterion: in this case, without an approved exception, version, access or rehearsal gaps keep handover pending. An alternative package may be valid if it satisfies the same content, control and usability conditions. Exporting the wrong page is insufficient. The rehearsal establishes what was actually tested; it does not guarantee success in every incident or replace specialist review of production commands. Capture remaining assumptions so later shifts can tell where the evidence ends.
sequenceDiagram
participant APS
participant App
APS->>App: Restart
App-->>APS: Process running
APS->>App: Functional check
alt Expected result observed
APS->>APS: Record evidence and close
else Failed or inconclusive
APS->>APS: Keep incident open and investigate
endRelease 4 goes live on Saturday, but the main wiki describes release 5. RUN cannot access the private code wiki. Readiness remains pending until an approved applicable revision, authorized access and recorded rehearsal exist.
Common pitfalls
Confusing current branch with approved revision; using the author identity to accept RUN access; treating a well-rendered diagram as a correct process; confusing filters with transport failures.
Related topics: Branch policies and review · Operational acceptance criteria · Subscription troubleshooting
Useful operational documentation combines applicable content, authorized readers, practical verification and a communication chain reaching the right owners.
Reference: Publish a Git repo to a wiki · AZ-400 objectives 2026-07-27