For IT and engineering
The outage notice that explains the root cause in three paragraphs and never says when it will be back. Everything in it is true. None of it answers the question the reader actually has.
Technical writing gets composed in the order the thinking happened: what broke, why it broke, what we did, what it means for you. That is the correct order for a post-mortem and exactly backwards for anybody waiting to get on with their day.
How it usually arrives
“At 09:14 a failed certificate rotation on the authentication cluster caused session validation to fail intermittently. The rotation job had been running against a deprecated endpoint following last week's migration. We have reverted the job and are monitoring. Users may have experienced issues signing in.”
What the reader needed
“Sign-in is working again as of 09:52. If you are still stuck, sign out fully and back in — that clears it. No data was affected and nothing you saved is lost. Cause was a certificate job that ran against an old endpoint after last week's migration; it has been reverted and we are watching it.”
Same facts, same length, and the reader gets what they can do in the first sentence. The root cause did not need removing — it needed moving.
The curse here is genuine expertise. Once you know how something works you cannot un-know it, and every sentence you write quietly assumes three things the reader does not have. It is not carelessness — it is the thing that makes you good at the job.
Simple mode on a draft catches a surprising amount of it, because it flattens the assumed vocabulary. But the sharper tool is the agent: “Explain this back to me as somebody who has never used this system. Tell me where you had to guess.” The places it guessed are the places you left out a step.
That question is also the fastest way to find out whether a runbook works, which is otherwise only discovered at three in the morning by whoever is on call.
“Have you tried restarting it?” is a reasonable first question and it lands as an insult, because the user has spent twenty minutes on this and your first sentence implies they did not try the obvious thing.
The fix is not politeness, it is sequence: say what you think is happening, then ask. “This usually means the session did not refresh after the update — could you sign out fully and back in, and tell me if it persists?” Same request, and now it is a diagnosis rather than a suspicion about the user.
Worth running the first draft of a tense ticket through the agent: “Does this read as condescending? Quote the words.”
Or the config, or the connection string, or the stack trace with the internal hostnames in it. Not because anything here is careless with it — the trust and security page sets out exactly what happens to text — but because it is a third-party service and your own policy almost certainly has a view.
The prose around the technical detail is what benefits from a rewrite. The technical detail was already fine.