Software developers often share knowledge through blog posts, but many fall into avoidable traps that reduce the effectiveness of their writing. The most common mistake, by far, is meandering introductions where authors spend too much time on backstory before getting to the point. As the author of Refactoring English notes, readers frequently find themselves several paragraphs into a post with no idea what the author is trying to tell them. Developers want to know quickly whether an article is relevant to them and what they'll gain from reading it, so the title and first three sentences should answer: 'Did the author write this for someone like me?' and 'How will I benefit from reading it?'.
Another significant anti-pattern is overreliance on links to explain terms rather than providing brief explanations inline. Bloggers often want to mention a term the reader might not know, but instead of offering a short definition, they slap a link on the term and consider the problem solved. However, this forces readers to interrupt their flow and leave the article to understand a single word, which creates a poor reading experience. The solution is to summarize the essential information needed to follow the article while treating external links as bonus material rather than prerequisites, ensuring readers can enjoy and understand the content from start to finish without clicking any links.
This image relates to the article's point about developers wanting to quickly assess an article's relevance and benefit, which should be evident in the title and first sentences.
This image illustrates the meandering introductions anti-pattern where authors spend excessive time on backstory before getting to the point, as discussed in the article.
Excessive formality is also a frequent issue, as beginner software bloggers mistakenly believe they must write in a stiff, overly formal way to be taken seriously. In reality, the field of software development is one of the least pretentious white-collar jobs, and readers are often wearing pajamas and flip-flops while eating cereal at their keyboards. They don't expect or want writing that sounds like a legal document. Instead, bloggers should write the way they talk in real life, embracing a casual, personable, and unpretentious style that sounds like telling a story to friends at lunch, as exemplified by renowned software bloggers like Joel Spolsky, Kathy Sierra, Terence Eden, and Raymond Chen.