Tom Bedor wrote how to write good short docs. Most of it lands. Key takeaways, with some riffing:
Optimize for short attention spans. Think in tiers: the 5-second glance (title and first line), the 5-minute skim (summary and headings). This means: clear titles — the most important line in any doc. A concise summary at the top covering what's in scope and what's not. Strong headings. Collapsible/tabbed sections where the format allows.
I have only made this letter longer because I have not had the time to make it shorter.
— Blaise Pascal, Lettres provinciales (Letter 16, 1657)
Align with reader interest. Write "doing XYZ helps us accomplish {thing people already care about}."
Don't bury the lede. Put the point up front. Background context can come later, or go in an appendix.
The English language hates the slightest whiff of dishonesty, even levels so small you wouldn't naturally notice them yourself. It punishes you by making your writing worse.
— Scott Alexander, Half A Month Of Consolation Writing Advice
Take a stand. If you're writing a decision doc, state a clear decision — give alternatives a "Why not X?" section, but don't give them equal billing just to seem balanced.
Build consensus offline. Docs are bad at building consensus. They're good at documenting it. Write a rough draft to get your key ideas down, then reach out to stakeholders — sort out pushback before you publish. The doc formalizes what people agreed to, not what you wish they'd agree to. "Every doc is approved or rejected before it is written."
Ship it incomplete. A timely, incomplete doc beats a comprehensive one that arrives too late. Acknowledge unknowns, leave placeholders, fill in details later. Attention to an issue has a short shelf life.
Get feedback on drafts early. Don't polish in isolation. Share rough drafts with peers - the feedback loop matters more than the first draft.
Connect related docs. Link to something: the repo, the Jira board, a prior doc, a Slack thread.
Use Excalidraw. Diagrams good.
Excerpts
If your doc can be summarized by, "everyone should care more about XYZ", it's probably not a very good doc!
Use AI as your editor, not your ghostwriter.
People give very little attention to text or imagery that other people have generated. If I'm interested in what AI has to say about something, I can have it generate it myself.
In the age of Google docs, every doc can be changed at any time, so every doc is a living doc. Similarly, once a doc has been shared, it's time to remove the WIP label.
"If a doc is written in a forest, and no one has the link, does it create business value?"
— George Berkeley
The hardest part of a good (short!) doc isn't the writing. It's knowing what to cut, who you're writing for, and what only you can say.