软件博客写作中的反模式清单
Anti-Patterns in Software Blogging
我在软件博客中总结了初学者常犯的错误：冗长的开场白、假设读者无所不知、过度依赖外链、强行续集式写作、过于正式的语气，以及移动端排版和字体可读性问题。开发者喜欢细节，但读者需要快速获得价值。文章强调，标题和前三句话必须明确回答‘这篇文章适合我吗？’和‘我能得到什么？’。不要指望读者去读你的前一篇博文，也不要让他们点击链接才能理解内容。写作应像日常对话一样自然，避免AI生成的千篇一律风格。最后，务必在移动端预览你的博客，确保没有横向滚动和对比度过低的问题。
你不是在写给1988年IBM的80岁高管看，你的读者可能正穿着睡衣、踩着拖鞋，一边吃麦片一边读你的文章。
HN 评论区
92- phreack
我一直坚持认为，教育不是讲故事，也不该按讲故事的方式来构建。人们总想把“反转”和“揭秘”留到最后以追求最大冲击力，但这其实有害无益。恰恰应该反过来，在紧扣主题的前提下，做到“剧透式”和重复式。就像一场好的演讲，你应该先说你要讲什么，然后展开讲，最后总结你讲了什么。
大语言模型（LLM）让这个问题变得极其严重。想象一下，你如何用寥寥数语从技术角度解释 MCP 是什么？再去试着搜索看看。你会看到堆积如山的页面和文字，却永远无法切中要害。
- jrochkind1
有些周，我觉得我看到的大部分软件博客现在都是大语言模型（LLM）写的。它们通常烂透了。
也许有人可以把这些反模式告诉大语言模型？说真的，这会有帮助吗？
当然，我更希望人们亲自写下他们期望我——作为一个活生生的人类——去阅读的文字。
- ram1500natrluvr
“漫无目的的开头”可能是迄今为止最常见的错误，但迄今为止最具破坏性的错误，却是未能将主题与读者熟悉的事物联系起来（反模式 #2）。有些内容确实需要一定的专业知识或前置条件才能开始理解，但我反复在软件博客、README 等文档中看到，作者未能回答“这到底是什么？和我熟悉的东西相比如何？如果我对相关事物一无所知，我为什么要去了解它？”
这几乎适用于软件领域的方方面面。新工具？新设计模式？新库？语言惯用法？新语言？或者用更现代的视角来说，新模型？新框架？新框架选项？新使用模式？请先简要总结一下没有该项目时的情形，以此传达该项目本身旨在解决的问题。然后再深入细节，探讨它与其他方案的对比。
也许这只是我大脑处理信息的一种特定方式，觉得这类信息很直观，而缺失这类信息则特别令人恼火。
- zrail
“做这个不做那个”类的清单总是具有语境性和情境性的。其中一些建议在专业或商业网站的语境下说得通，但在采纳建议前，请确保你的目标与之相符。
如果你是在个人博客上写作，那么就把所有这些建议当成一撮盐来对待（take with a grain of salt），至于这撮盐该有多大，全凭你个人感觉。就我个人而言，那撮盐的大小大概相当于一个悬在悬崖边、正等着不知情的清单体作者（^h^h 即卡通角色“傻大猫”）掉下去的 ACME 保险箱。
- linsomniac
上周，在点击了一个 HN 链接后，我不禁觉得，技术博客也开始需要那种在美食博客界大行其道（且是好事）的“直达食谱”链接了。