refactoringenglish-com

Writing a software design doc helps developers think through key decisions before implementation, saving development time and coordinating design choices across teams. The author, drawing on experience at Google, Microsoft, and their own companies, emphasizes that effective design docs should clearly articulate the hard problems being solved and facilitate feedback from teammates.

The article outlines common flaws in software tutorials and presents 17 rules for writing effective ones, including writing for beginners, promising clear outcomes, making code copy/pasteable, and minimizing dependencies. It emphasizes clarity, beginner-friendly language, and keeping tutorials focused on a single concept.

The article argues that software developers should stop using passive voice, despite conflicting advice from English teachers and style enthusiasts. It explains that passive voice is less direct and clear than active voice, making technical writing harder to understand.

The article shares best practices for commit messages based on 20 years of software development experience. It covers what to include (descriptive titles, motivation, breaking changes, testing info) and what to leave out (obvious code details, short-term discussion, preview URLs).

Many developers struggle to attract readers to their blogs not because their ideas are weak, but due to common, fixable mistakes in how they present those ideas. The article explores why these errors drive audiences away and how recognizing them can dramatically improve readership.

This article argues that effective software release announcements should focus on how they improve the user experience, rather than simply listing new features like a rewritten changelog. It emphasizes that announcements should clearly show users how their experience is better than before.

The article presents techniques for software developers to write more effective emails, emphasizing that clear communication saves time, reduces misunderstandings, and increases professional recognition within a company.

The article provides practical techniques for getting meaningful feedback on software design documents, drawn from the author's experience as both author and reviewer. It addresses common challenges such as preventing design reviews from dragging on for months and ensuring reviews yield material improvements to the design.

A developer with 20 years of experience explains why they prioritize clear writing on engineering teams. They argue that writing is a force multiplier for technical work, helping to clarify thinking, improve onboarding, and reduce miscommunication.

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.