What happened
A post on Anti-patterns in software blogging reached the Hacker News front page this week. It lists common mistakes of beginner writers: meandering before getting to the point, assuming the reader knows what the author knows, and leaning on links to explain terms instead of explaining them on the page.
It is about blogs, not operations. But the same mistakes show up in the documents engineers write for each other.
Why it matters
In a company without a platform team, the person reading your runbook or alert text at 3am is often not the person who wrote it. It may be a backend developer who has never touched the cluster, or a new hire in their first month.
The three mistakes translate directly:
- Meandering: an alert that opens with history or context before saying what is broken makes the reader hunt for the point.
- Assumed knowledge: a runbook that says “just drain the node and check the CNI” works only for someone who already knows what that means.
- Links instead of explanations: “see the wiki” or “see the vendor docs” sends a tired person off to read a long page when they need one sentence.
None of this is a tooling problem, so a new monitoring product will not fix it. It is a writing problem, and it is cheap to improve.
What to do this week
- Pick your five noisiest or most important alerts. Check that the first line says what is wrong and who is affected, in plain words.
- Ask someone who did not write a runbook to follow it cold. Note every point where they stall or ask a question, then fix the text.
- List the terms a new team member would not know, and add a one-sentence explanation where each appears.
- Where a runbook says “see link”, add a short summary of the relevant step beside it. Keep the link as a bonus, not a requirement.
- Put the first action to take at the top of each runbook, and the background underneath.
Need a hand?
Clear alerts and usable runbooks are part of good observability, alongside dashboards and metrics. Our team can review your alerting and incident documentation and help you cut noise and make it readable by whoever is on call. Read more about our observability work; the first call is free and is with an engineer.
Source: Anti-patterns in software blogging
Related service: Monitoring & Observability