💬 Why This Page Exists
A runbook with a hallucinated flag is worse than no runbook. It
fails silently, at the exact moment someone is relying on it — often someone
who doesn't have the context to notice the step is wrong until it's already caused a
problem. A change log entry that quietly overstates certainty teaches the next reader
the wrong lesson about what actually happened. Neither failure is AI's fault in any
meaningful sense. Both are entirely preventable by one habit: reading what it
produced before anyone else does.
Pages 1 and 2 both end with a version of this warning. This page is where it gets
the space it deserves — not as a disclaimer tacked onto the bottom, but as the
actual practice that makes the rest of the series worth using.
🔍 The Review Habit That Actually Works
"Review it before publishing" is easy to say and easy to skip when you're busy,
which is exactly when documentation gets written. A checklist that takes thirty
seconds is more likely to survive contact with a real workday than good intentions.
-
🔎
Does every command match what you actually ran?
Not "close enough" — the exact flag, the exact path. A single wrong character in a path is the difference between the runbook working and someone deleting the wrong thing.
-
📅
Is anything time-sensitive stated as if it's permanent?
"The current version" or "as of now" ages badly in a document meant to outlive the session it was written in. Either date it or phrase it so it stays true.
-
🎯
Does the confidence level match what you actually felt?
If you weren't sure why a fix worked, the document shouldn't sound sure either. AI writes in clean declarative prose by default — that's a style choice, not evidence of certainty.
-
🤝
Could someone else actually follow this without asking you a question?
The real test. If you'd need to explain a step out loud, that step isn't finished yet.
The riskiest failure is the one that reads well. A rough, ugly
runbook with a mistake in it tends to get double-checked, because it looks
unfinished. A polished one gets trusted on sight — which means a polished mistake is
the one most likely to actually cause damage.
🧰 Tool-Agnostic Guidance
Everything in this series works with any of the CLI tools already covered
elsewhere on this site — the review discipline above applies no matter which one you
reach for. A few notes on where each one tends to fit best for documentation work
specifically:
| Tool |
Where it fits for documentation |
sgpt |
Fast, pipe-friendly — good default for the "paste history, get a draft" workflow used in Pages 1 and 2 |
aider |
Better suited when the documentation lives alongside code in a repo and should be edited in context, not drafted separately |
fabric |
Worth it if you find yourself running the same documentation prompt repeatedly — turn it into a reusable pattern instead of retyping it each time |
| Claude |
Better for longer, more exploratory writeups where you're still working out the structure as you go, not just formatting a known shape |
None of this is a strong recommendation to switch tools. If you already have one in
your daily workflow, the review habit above matters far more than which tool
produced the draft.
🏁 The Point of All Three Pages
Documentation has always competed with the next fire for your time, and it has
always lost. What AI actually changes is the cost of writing it down — not to zero,
but low enough that "I'll document it later" stops being the honest choice. The
runbook and the change log entry from the worked examples in Pages 1 and 2 took a few
minutes each, on top of work that was already done. That's the whole case for using
this: not that the documentation is better than what you'd write yourself, but that it
actually gets written.
The value isn't in the polish. It's in the fact that the runbook exists at all when
the next incident happens at 2 AM, instead of someone re-deriving the fix from
scratch under pressure. Read it before you save it, and let AI handle the part that
was never the hard part anyway.