TL;DR
Get the latest gadgets delivered free with Prime
- Fast, free delivery on millions of items
- Prime Video, Amazon Music and more included
- Member-only deals all year
A report on Refactoring English catalogues recurring anti-patterns in software blogging, led by meandering introductions and assumptions about what readers already know. Its advice is to state an article’s audience and value early, explain essential terms on the page, and use links as optional further reading.
Refactoring English has published a report identifying common anti-patterns in software blogging, arguing that habits such as slow introductions, unexplained technical assumptions and excessive reliance on links can make technical posts harder for readers to follow. The article offers writing advice rather than research findings, with its central recommendation to make a post’s audience and payoff clear early.
The report’s author says meandering introductions are the most common problem they encounter. Developers may open with backstory or historical context before explaining what the article is about, leaving readers several paragraphs in without a clear sense of its purpose. The proposed test is whether a reader can tell from the title and first three sentences both whether the post is for them and what they will gain from reading it.
The article also cautions that material placed before the main point—including a subtitle, biography, image or quotation—adds to the reader’s effort. Such elements can still belong in a post, the author says, but should not obscure the reason to continue. The report illustrates the approach with an example of a Go testing article that states its topic and says it can teach a technique quickly.
Other entries address writing for readers with less technical knowledge than the author, linking out instead of providing a short explanation, adding unrelated follow-up topics, excessive formality, basic HTML rendering problems, pages that overflow on mobile screens and fonts that are difficult to read. The supplied source excerpt explains the first several points in detail, but does not provide the full discussion of every item in its list.
Making Technical Posts Easier to Read
The guidance addresses a practical problem for developers who publish tutorials and technical explanations: readers may leave before reaching the useful material if the post delays its point or assumes knowledge they do not have. Clear openings can help readers decide quickly whether an article matches their needs, while brief definitions reduce the effort required to follow its argument.
The advice about links is especially relevant to explanatory writing. A link can provide authority or further detail, but making it necessary to understand the main article can interrupt the reader’s progress. The report recommends giving enough explanation on the page for the intended reader to understand the post, while retaining links as optional additional resources.
These are the author’s editorial observations and recommendations, not findings from a survey or measured study in the supplied material. Their value is as a checklist for writers and editors reviewing whether a technical post communicates its subject, audience and central benefit without unnecessary friction.
technical writing guide for developers
As an affiliate, we earn on qualifying purchases.
As an affiliate, we earn on qualifying purchases.
The Article’s Reader-First Advice
The report applies the software-development idea of an anti-pattern—a recurring approach associated with poor outcomes—to the craft of blogging. Rather than focusing on code quality, it considers how a post is introduced, explained and presented across different screens.
On audience assumptions, the author contrasts a jargon-heavy introduction to Docker with a plain-language description of it as a tool for packaging an application and its dependencies in a consistent environment. The point is not to avoid technical terms altogether, but to judge whether the intended reader is likely to understand them and explain what is necessary.
The source also includes a comment from Tyler Cipriani, who said that comparing assumptions in a draft with a written list of what the target audience knows changed how he thought about editing. The report’s broader approach is to imagine a real reader, identify what that person already understands, and revise the post accordingly.
“Comparing your list against the assumptions in my draft is pretty mind-blowing.”
— Tyler Cipriani
As an affiliate, we earn on qualifying purchases.
Scope and Evidence Behind the List
The supplied material does not give a publication date, readership data or a method for measuring how often each anti-pattern occurs. The claim that meandering is the most common mistake is the author’s account of what they encounter, not a quantified industry-wide ranking.
The source excerpt ends during its section on overreliance on links. Although it names additional patterns—including mobile page overflow and unreadable fonts—it does not include the full explanation or supporting examples for all of them. It is also unclear from the supplied material whether the report has been updated since publication.
readability tools for technical articles
As an affiliate, we earn on qualifying purchases.
As an affiliate, we earn on qualifying purchases.
How Writers Can Apply the Checklist
The article does not announce a follow-up study or a scheduled next development. Its immediate use is as an editing checklist: identify the intended reader, state the post’s payoff near the start, explain unfamiliar concepts in plain language, and check that links supplement rather than replace needed explanations.
Writers can also review how the post renders on mobile devices and whether its typography is readable, two presentation problems named in the report. Whether applying these recommendations improves reader engagement is not measured in the supplied source; that would require readership or usability evidence beyond the article’s advice.
As an affiliate, we earn on qualifying purchases.
Key Questions
What is the report about?
It catalogues recurring software blogging anti-patterns, including meandering introductions, assumptions about reader knowledge, overreliance on links and presentation problems.
What should a software blog post explain early?
The report recommends making clear from the title and first three sentences who the post is for and what readers can get from it.
Does the report say writers should avoid links?
No. It says links can be useful, but readers should not have to leave the article to understand its main points. Explain the essential material on the page and use links for optional further reading.
Is the list based on a formal study?
No formal study or dataset is described in the supplied source. The ranking and recommendations are presented as the author’s editorial observations.
Source: hn
Halloween Picks
halloween
As an affiliate, we earn on qualifying purchases.
![Re: [PATCH] OOM_pardon, a.k.a. don't kill my xlock (2004)](https://geeksalad.org/wp-content/uploads/2026/06/re-patch-oom-pardon-a-k-a-don-t-kill-my-xlock-2004-featured-560x300.jpg)
