refactoringenglish-com

一份优秀的设计文档能为你节省数年的开发时间。它迫使你在投入错误实现或走入死胡同之前，先想清楚关键决策。这也是协调团队成员及合作团队之间设计决策的最佳方式。作者在谷歌、微软及自己的公司中撰写过大量设计文档，虽然具体形式各异，但核心原则一致：设计文档应阐明待解决的核心难题，并帮助团队成员提供反馈。

大多数软件教程都存在严重缺陷——要么遗漏关键细节，要么隐含与读者预期不符的假设。本文总结了17条简单实用的规则，帮助你在海量平庸指南中脱颖而出，写出真正优秀的软件教程。从"为初学者写作""标题承诺清晰结果"，到"使用可复制的代码片段""保持代码可运行状态"，每一条都直击教程写作的痛点。

你的高中英语老师可能警告过你，被动语态是危险且被禁止的。但当你长大后，又有人告诉你被动语态很酷，想用就用。如今风向再度转变——如果你是一名软件开发者，请停止使用被动语态。英语中的句子只有两种结构：被动语态或主动语态。

有效的提交信息能简化代码审查流程并促进长期代码维护。本文基于作者20年的软件开发经验，分享了如何撰写有用提交信息的具体方法，包括组织信息的结构、应包含的关键内容（如描述性标题、变更动机、影响总结、外部引用等）以及应避免的内容。文章还提供了一个实用提交信息的示例，帮助开发者提升团队协作效率和代码可维护性。

一位开发者因博客无人问津而放弃写作，但问题并非观点无趣，而是表达方式存在许多常见错误。这些错误其实很容易修正，一旦学会识别，就会觉得显而易见，但有些博主却常年犯同样的错误。文章揭示了这些致命问题及其改进方法。

一篇发布公告的本质是展示用户今天的体验比昨天更好。然而大多数发布公告只是罗列新功能，完全脱离了真实用户的使用场景，本质上就是一篇文笔略好的变更日志。真正优秀的发布公告应聚焦于用户视角，而非功能本身。

对于软件开发人员而言，写好邮件极具价值。优秀的邮件能节省时间、减少误解，还能在公司内部赢得认可。本文介绍了一些少有人使用但十分有效的邮件写作技巧，帮助你提升沟通效率与专业形象。

你花了几周时间精心撰写软件项目的设计文档，但接下来该怎么做？如何从团队成员那里获得有价值的反馈？如何避免设计评审拖上好几个月？作者结合自己作为设计文档作者和评审者的多年经验，分享了让评审流程更顺畅、切实改进设计方案的有效技巧。

一位拥有20年开发经验的程序员分享了他对清晰写作的执着追求。每当加入新团队，他首先会更新入职文档，并记录所学内容，鼓励同事一起参与。当其他开发者质疑为何要在"软技能"写作上投入精力时，他用自己的实践回答了这个问题。

这个练习测试你在软件开发语境中识别被动语态的能力。你需要判断每个句子是否包含被动语态，并选择"主动⚡"或"被动😴"来回答。

这是针对Tyler Cipriani关于Git大文件未来文章的初稿编辑笔记。通过明确目标读者、聚焦实用内容、优化结构，最终文章在Hacker News、Lobsters和Reddit的Git版块均登上榜首，获得热烈反响。

本文提供了17条编写高质量软件教程的实用规则，包括为初学者写作、在标题中明确承诺结果、展示最终成果、确保代码片段可复制粘贴等关键建议，帮助作者在众多平庸指南中脱颖而出。

文章探讨了被动语态在技术写作中的争议，指出虽然高中英语老师曾警告被动语态的危险性，但如今软件开发人员应避免使用被动语态，转而采用更直接的主动语态表达。

这个练习测试你在软件开发语境中识别被动语态的能力。你需要判断每个句子是否包含被动语态，并选择"主动"或"被动"选项来检验你的语法识别技能。

有效的提交信息能简化代码审查过程并帮助长期代码维护。本文基于作者20年软件开发经验，分享了编写有用提交信息的实用建议，包括信息组织结构和应包含的关键内容。

本文介绍了"HN人气竞赛"项目的评选方法，包括个人博客的定义标准、评分聚合规则以及数据更新频率。该项目统计Hacker News上获得至少20分的个人博客链接，并汇总各域名至少500分的总得分。

本文探讨了开发者博客无人问津的常见原因，指出即使有深刻见解，若在呈现方式上犯下基础错误也会赶走读者。这些错误通常易于纠正，但许多博主却长期忽视。

软件发布公告应聚焦用户体验的改善，而非简单罗列功能更新。优秀的公告能让用户直观感受到产品如何变得更好用，而不仅仅是技术变更的清单。

对于软件开发人员而言，撰写高效邮件具有巨大价值。好的邮件能节省时间、减少误解，并帮助你在公司内获得认可。

作者在《重构英语：软件开发者高效写作》一书中，通过增量发布方式获得读者实时反馈。在完成约50%内容后，作者希望确保剩余章节能真正满足读者学习需求。

开发者兼播客主持人Adam Gordon Bell分享了他通过博客写作成功吸引客户的经验，包括如何让文章登上Hacker News首页、发现吸引潜在客户的主题、提升写作技巧以及尊重竞争对手的价值。

作者回顾了20年编程生涯中阅读过的数千篇软件文章，从中精选出真正改变其思维方式的核心篇章，包括Joel Spolsky的《乔尔测试》、Alexis King的《解析而非验证》等十篇影响深远的经典作品。

本文分享了如何从团队成员那里获得关于软件设计文档的有用反馈，避免设计评审拖延数月。作者基于多年作为文档作者和评审者的经验，总结出帮助评审过程顺利进行并实质性改进设计的技巧。

《Crafting Interpreters》是一本教授如何从零开始构建编程语言的优秀书籍，其引言部分尤为出色。作者分析了该引言之所以引人入胜的原因，指出开发者通常不擅长写引言，因此值得深入研究其成功之处。

本文分析了2025年Hacker News上最受欢迎的个人博客作者，通过统计个人博客在平台上的表现来识别年度热门博主，不包括公司或团队博客内容。

作为一名拥有20年经验的开发者，作者始终重视清晰写作的重要性。他通过更新团队文档和鼓励同事记录所学，强调写作这一"软技能"对技术工作者的价值，反驳了"写作只是技术作家和产品经理职责"的观点。

作者为同一个开源Web应用创建了三份设计文档：一份耗时16小时手工编写，一份使用Claude Opus 4.6生成，一份使用GPT-5.4生成。AI版本仅需几分钟即可完成，但都基于相同的设计文档结构和书籍章节作为提示。