Urgent.News

What's breaking now, across hundreds of outlets.

Tech

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.

Every outlet that reported this, and when →

Read the original at refactoringenglish.com →

Report a problem with this story

More in Tech

Security updates for Wednesday

Security updates have been issued by AlmaLinux (bind, dovecot, freerdp, kernel, mariadb-connector-c, mod_auth_openidc, nodejs22, nodejs:22, sudo, and vim), Debian (node-shell-quote, puma, rails…

Sentiment analysis on YouTube comments with Python: handling sarcasm, emoji and spam

Comments are the cheapest audience research you have, and the hardest to read. A video with a few thousand of them is too many to skim, and a single sentiment score from a library will mislead you.

  • YouTube comment sentiment analysis is challenging due to noise and misinterpretation
  • Clean data by excluding creator comments, links, short comments, and duplicates
  • Validate tool against hand-labeled sample and adjust model or prompt as needed

More from Wednesday 7 October →