-
Meandering is the most common mistake in software blogging.
-
When a developer starts reading a blog post, they’re trying to answer two questions:
- Did the author write this for someone like me?
- How will I benefit from reading it?
Give yourself the title and the first three sentences to answer both questions.
-
Preamble (e.g., a subtitle, a bio, an image, or a quote) still counts as meandering.
-
Remember: Everything you put in the reader’s path is extra work that chips away at their finite supply of focus. Give the reader a compelling reason to continue reading. Make it in the title and the first three sentences of your blog post.
- Minimize assumptions about the reader’s background knowledge, especially for a technical term.
- Tip: Think of a person you know in real life. Read your article as that person and identify which terms feel unfamiliar.
❌ Assign firewall rules to prevent external traffic from reaching your database.
✅ A firewall is a system that restricts how hosts and networks communicate with an app. You can increase your web app’s security by configuring firewall rules to only allow inbound requests to your database server when they originate from your app server.
Instead of relying on a link to do the work for you, summarize the relevant information behind a link. Namely, link to useful resources, but make them a bonus rather than a prerequisite. Keep the reader on the page. Your target reader should be able to enjoy and understand your article from start to end without clicking any links (or even hovering for tooltips)!
❌ In part one, we learned about quintuply linked lists and how they can 100x your daily LOC output. In today’s post, I’ll show you how goto statements let you scrunkmax (a term I invented in part one — remember?).
It’s fine to refer to your previous posts, but never do it in the very beginning. Assume most readers haven’t read your previous articles. Summarize what was relevant rather than expecting the reader to go read all your prior posts.
