软件博客写作的几个反模式

Michael Lynch 对软件博客写作提出了一组很实用的提醒，尤其适合技术作者自查文章是否真正易读。

常见反模式

1. 开头过于迂回

很多技术文章在进入主题前铺垫太久，读者需要翻过几段背景、动机或闲聊，才能看到真正的问题和结论。对软件博客来说，越早交代文章要解决什么问题，读者越容易判断是否继续读。

2. 误判读者已有知识

作者经常默认读者知道某些概念、工具或上下文，但实际读者可能来自不同背景。技术文章不需要解释一切，但应当为关键术语和前提提供足够说明。

3. 假设读者读过你之前的文章

连续写作时，作者容易把前文当作默认背景。但单篇文章通常会被搜索、转发或单独打开。更稳妥的做法是：即使读者没有读过之前的内容，本文也能独立成立。

4. 过度依赖链接

一个常见问题是用链接代替解释：遇到术语、项目或背景时，只放一个链接，让读者自己点开补课。

Michael Lynch 给出的判断标准很直接：文章应该在读者不点击任何链接的情况下仍然说得通。

这并不是说不要放链接，而是不要把链接当作正文解释的替代品。链接适合延伸阅读，正文仍应承担基本说明的责任。

5. 写得过于正式

很多初写软件博客的人会误以为，只有使用僵硬、正式、论文式的语气，读者才会认真对待自己。

但他的建议是：像平时说话那样写。

在越来越多开发者把写作交给 AI 的环境下，软件博客很容易变得平淡、同质化。读者反而更需要有个性、有作者声音的技术写作。

对技术作者的启发

一篇好的软件博客不只是信息正确，还要让读者顺利读下去。可以用几个问题做自检：

• 文章是否很快说明了要讲什么？
• 关键概念是否在正文中解释清楚？
• 没读过前文的人能否理解？
• 链接是否只是补充，而不是正文的拐杖？
• 语气是否像真实的人在交流？

技术写作的目标不是显得高深，而是把复杂内容讲清楚。保留自己的声音，往往比堆砌术语更有说服力。