Michael Lynch treats a software blog post as an interface for a reader with limited time and context. A good idea can fail before the reader reaches it: the opening wanders, the explanation presumes too much, or the page itself is hard to read.
His practical checks:
- Use the title and first three sentences to say who the piece is for and what they will gain.
- Picture a specific reader, then audit technical terms against what that person actually knows.
- Explain essential context inline; links should extend the piece, not be required homework.
- Recap what matters from earlier posts so a sequel stands on its own.
- Write like a person, and test the rendered page on mobile for overflowing code and weak contrast.
The useful twist is that writing and delivery are the same job. If a code block forces horizontal scrolling, clarity in the prose will not rescue the experience.