[正文内容] Refactoring English

• Author

• Sample Chapters

• Exercises

• Tools

• Pre-order

如何写出程序员爱看的 Blog 文章

by Michael Lynch, 发表于 2025年3月27日 我最近和一个开发者聊过，他尝试写 Blog，但因为没人看而放弃了。我看了他的 Blog，立刻明白了他没有读者的原因。

这位开发者有有趣的见解，但他展示想法的方式犯了太多错误，把所有人都赶走了。可悲的是，这些错误很容易修复。一旦你学会识别它们，就会觉得它们显而易见，但有些 Blog 作者多年来一直在犯这些错误。

我知道，因为我也是其中之一。

我写软件开发相关的 Blog 已经九年了。我最好的文章有超过30万的读者，但很多都失败了，尤其是在最初的几年。

随着时间的推移，我学会了一些技巧，可以帮助一些Blog文章成功，以及一些导致其他文章默默无闻的陷阱。

• 为什么要听我的？
• 直奔主题
• 思考更大一级
• 规划通往读者的路线
• 展示更多图片
• 适应浏览者

为什么要听我的？🔗

我接下来要说一堆自夸的话来建立信誉，但这感觉很糟糕，所以我们直接了当：

• 我写 a software blog 已经九年了，每年吸引 30万-50万 独立访客。
• 我的文章在 Hacker News 首页出现了 超过 30 次，其中很多都达到了第一的位置。
  • 根据我自己发明的排名系统，我在 Hacker News 上拥有 第 48 个最受欢迎的 个人 Blog。
• 我通过撰写一篇关于我的产品的 popular blog post，成功启动了一项独立业务。
• 我的文章经常出现在 on reddit 和 Lobsters 上。

我的 software blog 每年收到 30万-50万 独立访客。 我并不声称自己是 world’s best software blogger，但我已经有了足够的成功和经验来分享一些有用的经验。

直奔主题🔗

软件 Blog 作者犯的最大错误是漫无边际。

通常，作者有一些有价值的见解要分享，但他们把前七段浪费在函数式编程的历史和 1973 年他们在 Bell Labs 的旅行上。当他们终于讲到真正有趣的部分时，每个人早就关闭了浏览器标签。 互联网上的注意力持续时间很短。 如果你在阐明观点之前犹豫不决，读者会寻找其他文章——字面上有数十亿篇——他们可以阅读。

那么，你如何说服读者留下来并继续阅读你的 Blog 文章呢？

当读者到达时，他们试图尽快回答两个问题：

1. 作者是为像我这样的人写的这篇文章吗？
2. 阅读它对我有什么好处？

给自己标题加上前三句话来回答这两个问题。如果你发现自己已经到了第二段，但还没有回答任何一个问题，你就麻烦了。

为了向读者表明你是为他们写作，请提及他们关心的话题，并使用他们认可的术语。如果你抛出术语或不熟悉的术语，读者会认为这篇文章不是为他们准备的并点击离开。

你的介绍还应该向读者清楚地说明阅读文章会给他们带来什么好处。你可以提供很多可能的好处：

• 读者可以在他们的工作或个人生活中应用的技术。
• 对影响读者工作或个人生活的概念的清晰解释。
• 读者可以更好地理解特定技术或行业的见解。
• 能引起读者共鸣的有趣故事。

示例：“if got, want: A Simple Way to Write Better Go Tests”🔗

我最近写了 an article 关于在使用 Go 编程语言时改进测试。

这是标题和第一段：

if got, want: A Simple Way to Write Better Go Tests 有一种非常棒的 Go 测试模式，但很少有人知道。我可以在 30 秒内教给你。 这篇文章立即回答了这两个问题：

• 作者是为像我这样的人写的这篇文章吗？
  • 这篇文章是为 Go 开发者准备的。
• 阅读它有什么好处？
  • 你将在 30 秒内学习一种新的测试技术。

思考更大一级🔗

当你写一篇文章时，你希望心中有一个读者类型。例如，如果你写了一篇名为“Debugging Memory Leaks in Java”的文章，你可能认为读者是中级到高级的 Java 开发者。

大多数软件 Blog 作者从未想过问：“这个主题是否有更广泛的受众？”

例如，“中级到高级的 Java 开发者”是“Java 开发者”的子集，“Java 开发者”是“程序员”的子集，“程序员”是“阅读Blog文章的人”的子集。 如果你写了一篇针对中级和高级 Java 开发者的文章，那么需要改变多少才能使这篇文章对任何经验级别的 Java 开发者都有吸引力？

通常，只需在文章开头添加一个或两个额外的句子来介绍一个概念，或者用更容易理解的术语替换术语。

Jeff : Sony 正在寻找一部未来科幻电影。 Nick : 太空中的香烟？ Jeff : 这是最后的疆域，Nick。 Nick : 但是它们不会在全氧环境中爆炸吗？ Jeff : 可能会。 但这很容易解决。 一句台词。 “感谢上帝，我们发明了…… 你知道，任何设备。” 感谢你吸烟 (2005) 所有 Java 开发者的集合大约是中级和高级 Java 开发者集合的 10 倍。 这意味着小的调整可以将你的文章的影响范围扩大一个数量级。

显然，你不能扩大每一篇文章的范围，而且你也不能永远扩大你的受众范围。 无论你多么善于解释背景概念，你的税务会计师永远不会阅读一篇关于 Java 中内存泄漏的文章。 关键不是撰写吸引所有可能读者的文章，而是注意到有机会接触到更大的受众。

示例：“How I Stole Your Siacoin”🔗

我最早的Blog成功案例之一是一篇名为“How I Stole Your Siacoin.”的文章。 它是关于我偷了一个 reddit 用户的加密货币（出于崇高的原因，我保证）。

最初，我以为这个故事会与关注一种名为 Siacoin 的小众加密货币的数百人产生共鸣。 在我编辑这篇文章时，我意识到你不需要了解任何关于 Siacoin 的信息就可以理解我的故事。 我稍微修改了一下，以便让从未听说过 Siacoin 的加密货币爱好者也能理解。

然后，我意识到我甚至可以向对加密货币一无所知的人解释这个故事。 我调整了术语，使用“钱包”和“密码”等普通人术语，并避免使用“区块链”或“Merkle 树”等加密货币特定术语。

这篇文章是我有史以来的第一个热门文章。 它不仅成为 /r/siacoin subreddit 上有史以来最受欢迎的故事，而且还在更大的 /r/cryptocurrency subreddit 上。 它达到了 the front page of Hacker News，即使那里的读者通常对以加密货币为重点的故事怀有敌意。 “How I Stole Your Siacoin” 只需要进行一些调整，就可以让对加密货币一无所知的人也能享受。

规划通往读者的路线🔗

假设你为 Python programming language 编写了你能想象到的最好的初学者教程。 你五岁的侄子和 80 岁的牙医都轻松愉快地完成了它。 每个阅读你的教程的人都成为了 Python 核心贡献者。

坏消息：没人会读你的 Python 教程。

“谎言！”你喊道。 “每年都有成千上万的开发者学习 Python。为什么我客观上很棒的教程不会流行？”

好吧，仔细想想。 点击发布后会发生什么？ 有人如何找到你的文章？

你可能在想：Google。

是的，你的朋友 Google 会索引你的教程，并使用其秘密的 Google 魔法来识别你的文章的卓越品质。 不久之后，你的教程将成为python tutorial的最佳搜索结果。

除非这不可能发生，因为已经有很多关于 Python 教程的网站比你的更受 Google 欢迎。 你甚至永远无法进入结果的第一页。 一篇新的Blog文章几乎不可能在 Google 中对搜索词python tutorial进行很好的排名。

好的，那么你将你的 Python 教程提交给 reddit。 /r/python subreddit 拥有超过 130 万订阅者。 如果即使其中 5% 的人阅读你的文章，那也是一个庞大的受众： /r/python subreddit 拥有超过 130 万订阅者。

哎呀！ /r/python 只接受文本帖子，不接受外部链接，所以你不能在那里发布你的教程。 /r/python subreddit 禁用了提交外部链接的选项。

好吧，那么你将它提交给 Hacker News。 他们接受任何东西，并让他们的成员决定什么是有趣的。 当然，他们会认识到你的工作的质量！

不，它也会在那里失败。 Hacker News 不喜欢教程，尤其是针对像 Python 这样的主流技术。

你可以尝试通过 tweeting it, skeeting it, or tooting it 来分享你的教程，但除非你已经在社交媒体上拥有大量的关注者，否则这也不会达到临界质量。

那么，答案是什么？ 你如何让人们阅读你令人惊叹的 Python 教程？

答案是你不要编写初学者的 Python 教程。

你需要一条通往读者的现实路径🔗

如果你想让人阅读你的 Blog，请选择一条通往读者的明确路径的主题。 在你开始写作之前，请仔细考虑读者将如何找到你的帖子。

考虑文章主题时要问的问题

• 读者通过 Google 搜索找到你是否现实？
  • 已经有 500 篇来自更成熟的网站关于同一主题的文章了吗？
  • 你的目标读者会搜索什么关键词？ 尝试搜索这些关键词，看看是否已经有来自知名领域的搜索结果。
• 如果你要将其提交给 Hacker News 或 Lobsters 等链接聚合器，那么 posts like yours succeed there 的频率如何？
• 如果你要在 subreddit 或小众论坛上分享它，它是否有任何机会？
  • 论坛是否接受Blog文章的链接？
    • 社区越大，关于外部链接和自我推销的规则往往越严格。
  • 像你这样的Blog文章在那里是否成功过？
  • 社区是否仍然活跃？

最好的计划是给你的帖子多次成功的机会。 如果你将一切都押在 Google 将你的帖子推到顶部，你可能需要几个月或几年的时间才能发现你是否成功。 如果你依赖 Hacker News 或 reddit 来告诉你你的文章是否值得阅读，他们会让你伤心很多次。

示例：“Using Zig to Unit Test a C Application”🔗

在 2023 年，我写了一篇文章，名为“Using Zig to Unit Test a C Application.” 。它是关于使用一种名为 Zig 的新型底层语言来为遗留 C 代码编写测试。

在我写这篇文章之前，我知道有几个地方可以分享它。 幸运的是，它们都奏效了：

• Hacker News 对 Zig 内容非常友好，因此我的文章 reached the #7 spot on the front page。
• Lobsters 对 Zig 内容非常友好，因此我的文章是 one of the top links of the day。
• Google 将我的文章提升为关键词zig unit testing c 的首位。
  • 它实际上甚至是zig unit testing 的首位，因为没有太多关于该主题的文章。
• /r/Zig subreddit 接受Blog文章的链接，即使是自我推销，因此我的帖子 reached the top spot in that subreddit。
• Ziggit 是一个对 Zig 相关文章表示欢迎的小众论坛，因此我的帖子 received 1,000 views from Ziggit。

展示更多图片🔗

你可以对Blog文章进行的性价比最高的更改是添加图片。

如果你的文章包含大量文本，请考虑是否有任何照片、屏幕截图、图表或图表可以使帖子在视觉上更有趣。

• 如果你正在谈论带有图形界面的程序，请显示屏幕截图。
• 如果你正在谈论应用性能或活跃用户等指标的改进，请显示图表。
• 如果你正在撰写有关服务器过载的文章，请显示仪表板或电子邮件警报中该外观的屏幕截图。
• 如果你正在解释一个难以理解的概念，请绘制一个图表。

我为我的大多数帖子 hire illustrators (包括这篇)。 我通常为每张插图支付 50-100 美元。 对于像嵌套圆圈草图 above 这样的简单图表，我使用 Excalidraw, which is free and open-source.

你也可以使用免费的库存照片和 AI 生成的图像，因为它们总比没有好，但它们比任何其他东西都差，包括糟糕的 MS Paint 图纸。 即使是糟糕的 MS Paint 图纸也比 AI 生成的图像更有趣。

适应浏览者🔗

许多读者首先浏览文章以决定它是否值得阅读。 在浏览期间让这些读者眼花缭乱。

如果读者只看到你的标题和图片，它会激起他们的兴趣吗？

浏览者最不愿意看到的是一堵文字墙：很长的段落，没有任何图片或标题来将其分开。 只是文字、文字、文字一直向下。

工具：像浏览者一样阅读🔗

这是一个 JavaScript bookmarklet，你可以使用它来查看你的文章在只有标题和图像时的外观。

• [Skimmify page](https://refactoringenglish.com/chapters/write-blog-posts-developers-read/<javascript:(function(){['p','code','ul','ol','pre', 'blockquote'].forEach(tag=>document.querySelectorAll(tag).forEach(el=>el.remove()))})();>)

将链接拖到你的浏览器书签栏，然后单击它以查看你的文章对浏览者的外观。

示例：无聊的结构与有趣的结构🔗

我在 2019 年写了我的文章“End-to-End Testing Web Apps: The Painless Way”，那时候我没有考虑结构。

如果你浏览这篇文章，它会让你想阅读完整版本吗？ Your browser does not support the video tag. 可能不会。 标题没有透露太多关于内容的信息，并且视觉效果令人困惑。

考虑我最近的文章“I Regret My $46k Website Redesign”。 Your browser does not support the video tag. 如果你浏览那篇文章，你仍然会看到一个好故事的骨架，并且有有趣的视觉元素来吸引读者。

其中一篇文章几乎没有吸引任何读者，另一篇文章成为我发布过的最受欢迎的文章之一，在其第一个星期内吸引了 15 万独立读者。 你能猜出哪个是哪个吗？

预购本书

这是我即将出版的图书 Refactoring English: Effective Writing for Software Developers 中的摘录。 $ 3,876 raised of $5,000 goal 78% Time left to meet goal: 3 days, 7 hours, 40 minutes Want to fund this so I can write the full book? Pre-order the book on Kickstarter to support the book. Pre-Order Now

In the nine years I've been blogging about software development, some of my posts have hit 300k+ readers, while others flopped, especially early on. I'm sharing all the lessons I learned the hard way about how to write popular blog posts for developers. refactoringenglish.com/chapters/wri...[image or embed] — Michael Lynch (@mtlynch.io) March 27, 2025 at 9:43 AM “Not Quite How Developers Read” illustration byPiotr Letachowicz. Steve Jobs illustration by Loraine Yow.