refactoringenglish-com

This article presents an interactive exercise that tests users' ability to identify passive voice in software development contexts. Users must click either "Active" or "Passive" buttons to classify each sentence presented to them.

This article presents blog editing notes for Tyler Cipriani's article about large files in Git. The editing process helped clarify the target audience, focus on practical lessons, and improve structure. The finished article achieved top positions on Hacker News, Lobsters, and the Git subreddit.

The article outlines 17 rules for writing effective software tutorials, addressing common flaws like missing key details and hidden assumptions. It emphasizes writing for beginners, promising clear outcomes, and providing practical guidance like making code snippets copy-pasteable.

The article discusses changing perspectives on passive voice, from school warnings to adult encouragement, before advising software developers to avoid it. It explains the difference between passive and active voice structures in English.

This exercise tests users' ability to identify passive voice in software development contexts. Participants must click "Active ⚡" for sentences without passive voice or "Passive 😴" for those containing passive constructions. The interactive tool provides feedback and tracks accuracy scores.

Effective commit messages simplify code review and aid long-term maintenance. The article provides guidelines for writing useful commit messages based on 20 years of software development experience, including what to include and what to leave out.

The methodology defines a personal blog as a single-authored written content site, including professional journalists' blogs. It aggregates scores from Hacker News submissions that received at least 20 points, excluding duplicates below that threshold. The data updates monthly, with occasional out-of-band updates.

A developer stopped blogging due to lack of readers, but his presentation mistakes were easily fixable. Many bloggers make similar errors for years without recognizing them.

The article explains that effective software release announcements should focus on how updates improve the user experience, rather than just listing new features like a changelog. It criticizes announcements that are disconnected from how real people actually use the software.

Effective email writing saves time, reduces misunderstandings, and helps software developers earn recognition within their company. The article discusses underused techniques for writing more effective emails.

The author is writing a book called "Refactoring English: Effective Writing for Software Developers" and publishing it incrementally. After completing about 50% of the book, they are seeking reader feedback to ensure the remaining chapters address what readers actually want to learn.

Developer Adam Gordon Bell discusses his blogging strategies for attracting customers, including techniques for reaching Hacker News' front page and finding topics that appeal to potential clients. He shares writing improvement methods and the value of respectfully covering competitors.

The author reflects on influential software essays that shaped their thinking over 20 years. They list 10 notable essays including Joel Spolsky's "The Joel Test" and Fred Brooks' "No Silver Bullet." The author considers Joel Spolsky the greatest software blogger and highlights his impact on their approach to software development.

The article provides techniques for obtaining meaningful feedback on software design documents based on the author's experience as both writer and reviewer. It aims to help streamline the review process and improve design quality through effective methods.

The introduction to Bob Nystrom's "Crafting Interpreters" book is praised as delightfully effective and compelling, standing out from typical developer-written introductions. The book teaches how to build a programming language from scratch while covering parsing, data structures, and virtual machines.

The article identifies the most popular bloggers on Hacker News in 2025, focusing on individual bloggers rather than company or team blogs. It explains the methodology used to determine which blogs qualify for inclusion in the ranking.

The author, a developer with 20 years of experience, emphasizes the importance of clear writing in software development. They prioritize updating onboarding documentation and encourage teammates to document their learnings, despite questions from other developers about focusing on this "soft skill."

The author created three design documents for the same open-source web app: one written manually over 16 hours, one generated by Claude Opus 4.6 with medium effort, and one by GPT-5.4 with high effort. The AI versions were produced in minutes using prompts that included design documentation guidelines and a skeleton structure.