Anti-patterns in software blogging
Article URL: https://refactoringenglish.com/blog/anti-patterns-software-blogging/ Comments URL: https://news.ycombinator.com/item?id=49992257 Points: 240 # Comments: 129
In the realm of software development, we document anti-patterns to identify traits that result in subpar results. It became apparent that crafting similar guidelines for software blogging would be beneficial. Thus, I've compiled a list of the most prevalent errors observed in beginner blog posts.
The primary issue with software blogging is meandering content. As I read through numerous posts, I frequently encounter authors who lose track of their thoughts, leaving readers confused about their intended message. Developers often start their posts with extensive backstory, historical context, and any other topic that comes to mind.
While this may be enjoyable to write, it doesn't necessarily captivate readers. From a reader's standpoint, there are countless other articles vying for their attention. Why should they invest time in reading yours if they don't perceive a payoff? Explain to your readers why they should continue reading your post.
When a developer commences reading your blog post, they are primarily seeking answers to two questions: What benefit can they gain from reading this article? How quickly can they obtain this benefit? Provide a clear title and the first three sentences to address both inquiries. Your article should offer a compelling reason for readers to invest their time.
A recent article I penned, "A Simple Way to Write Better Go Tests," effectively addresses this by explaining a Go testing pattern that many programmers are unaware of, teaching it to them in just 30 seconds.
While some bloggers manage to deliver a compelling introduction, they often clutter the reader's experience with additional elements like subtitles, bios, images, or famous quotes. Although these components can be included, they consume the "inspire the reader to continue" budget. Every element placed in the reader's path adds complexity, reducing their finite focus.
Effective educators compare new concepts to familiar ideas for their audience. For instance, when explaining Jellyfin, I might say, "Jellyfin functions like Netflix, but it's open-source and private, so nobody monitors your viewing habits." The challenge lies in understanding what your readers already know. In this article, I'll introduce Docker to developers who have never encountered it before.
Docker is straightforward; it's essentially a user-friendly interface for Linux cgroups. However, some developers may be unfamiliar with terms such as cgroups, jails, or *BSD. They may not even comprehend what Linux is, particularly if they're searching for an introduction to Docker. Rather than assuming your readers possess your exact knowledge base, minimize your assumptions regarding their background: Docker is a tool for packaging applications to ensure consistent, reproducible environments across all platforms.
Docker enables you to define your application's environment and dependencies using human-readable text files. These files capture your application's requirements, ensuring you fully understand its functionality even after years of modifications by various teams.
When writing a blog post, consider your target audience. What do they already know? Visualize a friend or colleague you regularly interact with. Create a list of terms they would readily recognize and those they would not. Review your blog post, and each time you encounter a technical term, assess whether your intended reader would comprehend it. This exercise yields fascinating insights.
Tyler Cipriani, while editing "The future of large files in Git is Git," challenged my assumptions about the target reader. Reflecting on this advice, it became apparent that my initial approach was insufficient.
Rewritten by urgent.news; may contain errors — check the original.
This story
This is one outlet's version. Read the fullest account.
- Anti-Patterns in Software Blogging simonwillison.net
- Anti-Patterns in Software Blogging refactoringenglish.com