技术博客写作的五个反面模式

原文要点

Simon Willison 转载推荐 Michael Lynch 的技术写作避坑清单：避免绕圈子开头、误判读者已有知识、假设读者读过你的旧文、过度正式的腔调、用堆链接代替解释术语；Lynch 的经验法则是读者一个链接都不点也应读得通。他还强调像说话一样用自己的声音写作——在大量开发者把写作交给 AI、文章日趋同质化的当下，带个性的文字更受欢迎。

这次做成什么

把五条反面模式变成一份发布前可逐条执行的自检流程，配一个可直接粘贴的 AI 审稿提示词和一段改写示范，改完一篇真实草稿。

准备什么

• 一篇待发布或草稿状态的技术博客文章，Markdown 或纯文本均可
• 可选：任意大模型聊天工具，用于运行审稿提示词
• 对目标读者的一个具体假设（岗位、经验年限、熟悉的技术栈）

具体怎么做

1. 砍绕圈子开头

   把第一段与标题对照：若第一段没有交代“这篇解决什么问题、读者能拿走什么”，整段删掉或改写成两句以内的直入式开头，直接从问题或结果说起。

2. 标定读者水平

   在文首心里选定一个具体读者画像。通读全文：超出该画像的术语就地补一句解释，低于画像的常识铺垫整段删掉，避免两头都得罪。

3. 链接断点测试

   把所有超链接临时去掉通读一遍，凡去掉后读不通的地方在链接前补一句解释；引用自己旧文的位置补一句独立可懂的背景，不假设读者读过。

4. 去正式腔、用自己的声音

   朗读全文，把“综上所述”“本文旨在”一类书面腔换成口语表达，保留第一人称和真实语气，但口语化不等于放任废话，仍要删冗余。

5. AI 终审

   把全文粘贴进下方审稿提示词运行，按返回的命中清单逐条修改，再发布。

可直接复制的材料

你是技术博客编辑。请按以下五条反面模式审查我贴的文章，逐条给出：是否命中、具体句子、改写建议。五条：1 绕圈子开头；2 误判读者知识水平（过深或过浅）；3 假设读者读过作者旧文，或必须点链接才能读懂；4 过度正式的腔调；5 缺乏作者自己的声音、像套话。最后给一个不超过三条的优先修改清单。文章如下：{粘贴全文}

{"checklist":[{"item":"开头两段内说明解决什么问题、读者能拿走什么","pass":"是/否"},{"item":"去掉全部超链接后文章仍读得通","pass":"是/否"},{"item":"引用旧文处都补了独立背景句","pass":"是/否"},{"item":"朗读无明显书面腔，第一人称语气一致","pass":"是/否"},{"item":"目标读者画像之外的术语均就地解释","pass":"是/否"}]}

输入与输出示例

本站虚构演示，改写范例非原文作者文字。

输入

原开头（虚构）：在这个快节奏的时代，技术日新月异，作为一名从业多年的工程师，我常常思考一个问题：我们为什么写博客？今天我想聊聊缓存。

对应输出

改写后：上周我们的接口 P99 延迟从 800ms 降到 120ms，靠的是给商品详情页加了一层本地缓存。这篇记录方案、踩到的坑和回退开关。——开头两句即交代问题与收获，删掉了“时代”“为什么写博客”这类绕圈内容。

做完检查这些

• 开头两段内出现“解决什么问题”和“读者能拿走什么”两个信息
• 全文去掉所有超链接后仍能读通，术语均有就地解释
• 引用自己旧文的位置都补了不看原文也懂的背景句
• 朗读全文没有明显书面腔句子，第一人称语气前后一致

容易卡住的地方

• 像说话一样写不等于放任口语冗余，改写后仍要删废话
• 判断读者水平没有客观标准，找一位目标读者试读比自测可靠
• AI 审稿可能把有个性的句子误判为“不正式”，最终取舍由作者决定
• 链接不是不能有，而是不能成为不解释术语的借口