Gains:
- Ability to produce runbook, post-mortem and architectural document skeleton from scattered notes with artificial intelligence
- Ability to enforce the discipline of imposing a 'ban on fabrication' and thoroughly testing and marking each runbook in a real environment
- Ability to understand that a wrong runbook is more dangerous than none and keep the documentation alive through the change process
Documentation and Information Management: Runbook, Architecture and Institutional Memory with AI
The most neglected but life-saving task of system management is documentation. When a system crashes and the person who built it is on vacation and there's no written word on how to recover, it's a long night for everyone. Documentation is the institutional memory that makes written and available how a system is set up, how it works, and what to do if a problem occurs. The most critical type of this memory is the runbook: an operational guide that tells you step by step what to do in a given situation (service crashed, disk full, backup failed). Here AI solves the "blank page" and "laziness" problem, which are the biggest enemies of writing documentation: it produces an organized runbook from your scattered notes, a procedure from a command history, a description from an architecture. But the critical principle: AI produces blueprints and skeletons; You're the one testing and validating each step to see if it's actually correct — a wrong runbook is more dangerous than no runbook at all.
In this unit, runbook, post-mortem (post-event investigation report), architectural documentation and knowledge base writing; Generating drafts with AI; and most importantly you will learn the risks of unverified documentation.
Why is the wrong runbook worse than no runbook?
This is the most important concept of this unit. A team without a runbook is cautious and suspicious in times of panic; thinks twice about every command. But someone with an “official” runbook trusts it blindly — in the middle of the night, under stress, executing the steps without question. If that runbook is released without being produced and tested by AI and has one step wrong (a wrong command, a missing prerequisite, a skipped fallback step), the result is disastrous. That's why every runbook produced with AI must be run from start to finish in a real environment and every step must be verified before it is published. An untested runbook is like a reassuring but empty promise.
Caution: Stamp a runbook with "tested: [date], [person]". Clearly mark untested drafts with the label “DRAFT — NOT VERIFIED.” So no one would safely apply unverified steps in a real crisis.
Anatomy of a good runbook
A good runbook consists of specific parts, and AI is good at building that skeleton: title and purpose (for what situation), prerequisites (what access, what tool needed), symptoms (when do I use this runbook), steps (with numbered, copyable commands), validation (how to recognize success after each step), rollback (how to undo if a step goes bad), and escalation (who do I call if I can't figure it out). You can give the AI your scattered notes and ask it to put it into this structure; You only ensure the accuracy of the content.
Step by step: Documentation production with AI
- Gather the raw material. Your command history, your notes, an old email, a chat log—real material, even if messy, is better than AI fabrication.
- Ask for structure. “Make this a runbook with the following headings: purpose, prerequisite, symptom, steps, verification, rollback, escalation.”
- Ban fabrication. "Don't add any commands, IPs, versions or steps that I haven't given you; mark any missing parts as [TO BE FILLED]." This prevents the most dangerous mistake — the seemingly plausible made-up steps.
- Mask. Use placeholder instead of actual host, IP, user; If the document is shared, the secret should not be leaked.
- Test it. Run the runbook from start to finish in a real (preferably test) environment. Fix any steps that are not working, missing, or unclear.
- Stamp and publish. Add test date, tester, and last update. The documentation is lively; It must be updated when the system changes.
three mini cases
Case 1 — 2 hours of work, 15 minutes. An administrator had been putting off documenting a backup restore procedure for months. He gave the terminal command history (masked) and a few scattered notes to the AI and inserted it into the runbook framework. The AI produced a neat outline in 15 minutes. The administrator spent the next 45 minutes running the draft from start to finish on a test server and fixing the two missing steps. The result: a tested, reliable runbook.
Case 2 — Caught falsely. A team had the AI write a service restart runbook but forgot to ban "fabrication". YZ added a "clear cache first" command, which seems logical but does not exist in that service. Fortunately, the engineer ran the runbook in the test environment; That command gave an error. The test step captured a made-up step that would create confusion in a real crisis.
Case 3 — Post-mortem accelerated. After a major outage, the team needed to write a post-mortem, but no one could get started. They handed the event timeline and masked logs to the AI and asked for a blameless post-mortem skeleton — summary, impact, timeline, root cause, corrective actions. The AI blueprint reduced an hour's work to ten minutes; The team devoted its energy to verifying facts and clarifying action items.
Four copyable templates
1) Generating a runbook skeleton:
Your role: senior SRE. Create a runbook from the masked notes/command history below. Headings: Purpose, Prerequisites, Symptoms (when to use), Steps (numbered, can be copied), Verification at each step, Rollback, Escalation. RULE: Do not make up any command/IP/version/step that I do not give you; write the missing parts [TO BE FILLED]. Material: [masked note]
2) Post-mortem without blame:
Your role: incident investigation facilitator. Write a BLAME-FREE post-mortem sketch from the following masked timeline and logs: Summary, Impact (duration/scope), Timeline,Root Cause (if verified), Contributing Factors,Corrective Actions (owner + priority). Don't blame the person, focus on the system. Don't write root cause without evidence. Data: [...]
3) Architecture/service description:
Write a service document from the following masked configuration/diagram information: what does the service do, what components does it consist of, what are its dependencies, how does data flow, what ports/protocols. Keep it technical but readable. Mark the relationship you're not sure about as "needs verification". Info: [masked]
4) Documentation refresher audit:
Review the following existing document and check for currency: (1) what sections are missing/obscure, (2) what steps appear untested, (3) what information might be outdated? Write down what I should ask/verify for each finding. Document: [masked document]
Weak prompt / Strong prompt
Weak prompt:
Write me a server maintenance runbook.
There is no real material. AI produces a text, entirely from its own general knowledge, that does not fit your environment or even contains made-up steps. This is a dangerous source of false confidence.
Powerful prompt:
Your role: senior SRE. Below is the masked command history and my notes that I implemented in the "payment service disk full" event. Create a runbook from these: Purpose, Prerequisite (access/tool), Symptom, Numbered Steps (with my commands), Verification at each step, Rollback, Escalation. Don't make me follow a command I didn't give; Make the blank [TO BE FILLED]. Put a "not tested" warning at the end. Material: [masked command history]
Document type
Contribution of AI
Mandatory contribution of man
runbook
Skeleton + layout
Testing in real environment, accuracy
Post-mortem
Outline + structure
Verify facts and root cause
architectural document
Description + flow
Confirm relationships and dependencies
Knowledge base article
quick draft
Currentness and accuracy check
Common mistakes
- Publishing untested runbooks. Unverified steps are blindly implemented in crisis; Wrong runbook is disaster.
- Not to impose the ban on fabrication. If you don't tell the AI "don't add what I haven't given", it will produce reasonable but unrealistic steps.
- Skipping masking. The secret is leaked when the document containing the real host, IP and user is shared.
- Not updating the document. Documents that are not updated when the system changes become misleading over time.
- Publishing without a stamp. It is not clear whether a document without a test date and status is reliable or a draft.
Tip: The best way to keep documentation “live” is to tie it to the change process: when a system changes, let updating the relevant runbook be one of the completion criteria for the change. AI speeds up the update, but you are the triggering process.
In summary
Documentation is institutional memory; The runbook is an operational guide that saves lives in times of crisis. AI produces organized drafts from your messy notes, solving the problem of blank pages and laziness. But the most critical truth is this: a wrong runbook is more dangerous than none at all because it is applied blindly in a crisis. So ban the AI from "fabricating", mask it, and thoroughly test and stamp each runbook in a real environment. Keep the document alive as the system changes. AI builds the framework; You are the one who guarantees accuracy and testing.
Application task
Choose a procedure that is not documented in your team (for example, restarting a service or restoring a backup). Mask your relevant command history and notes and have the AI create a draft using the "Runbook skeleton generation" template above; Be sure to impose a ban on fabrications. Run the draft through in a test environment and flag and fix any broken/missing steps. Add test date and tester information to the runbook. Write down the differences that AI produces and you correct in the process in 5 items.
checklist
- [ ] I created the runbook from real material (note, command history), didn't I make it up from scratch?
- [ ] Have I banned the AI from "adding commands/IPs/steps that I haven't given"?
- [ ] Have I masked sensitive information such as host, IP and user?
- [ ] Have I run and validated the runbook in a real/test environment?
- [ ] Have I added the test date, tester and last update information?
- [ ] Have I planned to link the document to the system change process and keep it up to date?