文章指出，技术文档常过于复杂，缺乏实用示例。开发者往往需要快速了解如何使用某个功能，而非深入理解其原理。作者以Python文档为例，说明即使简单如max()函数，其文档也预设了过多背景知识，导致查阅效率低下。理想的文档应优先提供简洁示例，再辅以详细说明。

标题：示例是最好的文档

在查阅技术文档时，95%的情况下只需要一个简单的示例就足够了，但95%的情况下在官方文档中却找不到这样的示例。

当前的技术文档往往默认面向那些已经深入掌握该技术生态的开发者。然而现实中，开发者每天需要在不同项目、语言和框架之间切换，这需要耗费大量精力来重建上下文理解。

以Python 3文档中的max函数说明为例：

max(iterable, /, *, key=None) 返回可迭代对象中的最大元素或两个及以上参数中的最大值...[后续还有5段说明]

要完全理解这个定义，开发者需要预先掌握： - 函数定义中*和/的含义 - "仅限位置参数分隔符"的概念 - 可迭代对象的定义 - 关键字参数的含义 - key参数的常规用法

相比之下，如果提供以下示例，开发者就能立即理解如何使用： max(4, 6) # → 6 max(['x', 'y', 'abc'], key=len) # → 'abc' max([], default=5) # → 5

Clojure社区的clojuredocs.org项目就很好地解决了这个问题，这个网站收集了开发者贡献的各种函数使用示例。比如into、spit和map等函数的页面都包含了丰富的实用示例，甚至还会展示相关函数的用法，极大提升了文档的实用价值。

由于大多数软件项目都缺乏完善的文档体系，作者表示自己经常不得不通过教程来寻找示例代码，而非真正需要教程指导。这反映出当前技术文档普遍存在的问题：过于注重技术细节的完整性，却忽视了开发者最需要的即用型示例。

以下是评论内容的总结：

支持示例文档的观点

1. 示例代码可作为单元测试，防止文档过时或错误

   • "Code examples can be executed as unit tests to prevent documentation regressions" (willquack)
   • "Even better if the documentation examples are part of the test suite!" (WalterBright)

2. 示例适合初学者快速上手，帮助理解工具的核心用途

   • "Examples are the best quick start documentation" (basemi)
   • "Examples let you grasp immediately how to use the library" (gbalduzzi)

3. 示例展示工具的“精神”，比单纯参数列表更直观

   • "examples often show the 'spirit' of the invention" (alliao)
   • "picking the thing up, tossing it about to get a feel of it" (gorgoiler)

支持完整文档的观点

1. 高级用户需要完整参数和功能说明，示例无法满足复杂需求

   • "For more experience devs, you want regular docs, with full parameter list" (theamk)
   • "Detailed explanation of all params... allows you to solve more complex problems" (gbalduzzi)

2. 仅有示例的文档过于基础，可能让用户困惑

   • "I am tired of rudimentary docs that only have examples" (satisfice)
   • "Google always drops me to the pages like Quickstart... But they are useless for advanced users!" (theamk)

中间立场

1. 两者结合是最佳实践，示例与完整文档互补

   • "You need both and there are no ways around that" (gbalduzzi)
   • "the best solution are both, where examples all have hyperlinks to the actual documentation" (adzm)

2. 文档类型应多样化，不同场景需要不同形式

   • "The Diátaxis framework provides a nice suggestion of different types of documentation" (smokel)
   • "Good documentation needs to have both" (bigstrat2003)

其他观点

1. LLMs的崛起反映文档质量低下

   • "This is why LLMs won... IT devs are so bad LLMs are better" (NedF)

2. 直接阅读源代码

   • "when possible... I just go and read the source" (ossusermivami)

3. 设计应直观，避免过度依赖文档

   • "If the technical spec... cannot be intuited from the signature... the method is probably trying to do too many things" (Paracompact)

总结：多数评论认为示例和完整文档各有价值，理想情况是两者结合。示例适合快速入门，而完整文档满足深度需求。部分用户对文档质量不满，甚至转向LLMs或直接阅读源代码。