Humanizing Artificial Intelligence in DevOps Documentation: Making Runbooks Easier to Create and Use

The Runbook That Lied to Me at 3am

The pager went off at 3:14am for a wedged OpenStack Neutron agent. I did what any tired engineer does: I opened the runbook. It told me to restart a service that had been renamed eighteen months earlier, pointed at a Grafana dashboard that 404'd, and assumed a network topology we'd migrated off of two quarters back. The runbook wasn't just unhelpful. It was actively lying to me, and I burned twenty minutes trusting it before I gave up and went to read the source.

That's the real problem with documentation. It isn't that we don't write it. It's that the moment we finish writing it, it starts rotting, and the cost of keeping it fresh is high enough that nobody pays it until the document has already betrayed someone at 3am. A runbook your team doesn't trust is worse than no runbook, because no runbook at least forces you to think.

This is where AI actually earns its keep in a platform org, and not in the way the marketing decks suggest. AI is not going to own your documentation. It's going to do the tedious first-draft labor — turning a resolved incident, a chunk of shell history, or a deploy diff into a structured skeleton — so a human engineer can spend their scarce attention on the part that matters: verifying the commands, marking what's unproven, and editing the robotic tone out so the team actually reads it. AI drafts. You verify and sign off. That distinction is the whole game.

Why "Humanizing" AI Is the Job, Not a Slogan

Let me be precise about what I mean by "humanizing AI," because the phrase gets abused. I don't mean making AI sound human to fool a reader. I mean keeping a human in the loop as the editor and owner of record, and doing the unglamorous work of turning a competent-but-soulless machine draft into something a colleague trusts.

Two things break trust in AI-drafted docs, and both are fixable by a human pass:

1. Unverified claims stated with confidence. An LLM will happily tell you to run systemctl restart neutron-l3-agent whether or not that's the actual unit name on your boxes. It doesn't know. It's pattern-matching. So the human's first job is to run every command, in a safe environment, and confirm it does what the draft claims.




2. The robotic tone. Machine drafts read like a compliance memo: hedged, repetitive, weirdly formal, full of "it is important to note that." Engineers smell that instantly and stop reading. Editing for voice and concision isn't vanity — a doc people skim past doesn't get used. That cleanup pass is legitimate, valuable work, and it's exactly the "humanizing" angle that matters.

If you keep those two responsibilities firmly with a person, AI becomes a force multiplier instead of a liability generator. I've written more about the philosophy of .

Postmortems: AI Handles the Timeline, You Own the Blamelessness

Postmortems are where AI's drafting strength and its judgment weakness are both on full display. The mechanical parts — assembling a coherent timeline from Slack threads, alert timestamps, and deploy logs, then drafting an impact summary — are exactly the tedious work that delays postmortems for weeks. AI eats that for breakfast.

But the blameless part is not a tone setting you toggle. It's an editorial and cultural stance that a human has to own. I give the model the raw timeline and explicitly instruct it:

Draft a blameless postmortem. Describe what the system did and what signals were available, never what a person "failed" to do. Frame every human action as a reasonable decision given the information available at the time. Sections: Summary, Impact, Timeline, Contributing Factors, What Went Well, Action Items. Mark any causal claim you can't support from the inputs with [UNVERIFIED].

The model will get you 80% of the way to neutral language. The remaining 20% — catching the sentence that subtly implies the on-call engineer should have known better — is human work, every time. Blameless writing is a skill, and the editing pass is where you apply it. If you haven't internalized what separates a postmortem people read from one that gets filed and forgotten, is half the productivity gain, because the quality of the draft is downstream of the quality of the prompt.

Deployment and Release Docs: Draft Straight From the Diff

Deployment documentation has a unique advantage: the source of truth is structured and machine-readable. A PR diff, a Terraform plan, a Helm values change — these are precise artifacts an AI can read directly, which means the draft starts from facts rather than recollection.

My workflow for release notes and deploy runbooks: pipe the diff or the terraform plan output to the model and ask for a deployment guide that includes pre-flight checks, the apply procedure, the blast radius, the rollback, and the post-deploy verification. Because the input is concrete, the hallucination rate drops sharply. The model isn't guessing what changed — it's reading it.

Pre-flight Checks

• Confirm the target workspace: terraform workspace show returns prod-us-east.


• 
  [ASSUMPTION] This plan adds 2 nodes and modifies the ASG launch template; no destroys. Re-run terraform plan and confirm zero resources to destroy before applying.

Rollback

The launch template change is versioned. To roll back, point the ASG at the previous template version and trigger an instance refresh — do not terraform destroy.

Even here, the human verifies the blast radius claim. "No destroys" is the kind of statement that's true until a provider upgrade quietly makes a field force-new, and a misread there is how you turn a routine deploy into an outage. The AI gets you a structured, mostly-correct draft fast; you confirm the dangerous parts with your own eyes. For a fuller treatment of wiring this into a real pipeline, my , where he writes about running production OpenStack, Kubernetes, and observability with AI in the loop. If your AI-drafted docs read like a robot wrote them, his Writing Humanizer pack is a toolkit for making machine drafts read like a human actually sat down and wrote them.