思考与写作stevelosh.com
教，而不只是告诉（2013）
Teach, Don't Tell (2013)
2013 — 2025，它一次次回到首页
黑点是上首页（≥ 50 分）的那次投稿，空心点是没冲上去的投稿，点越大分数越高。
导读
Steve Losh 这篇 2013 年的文章谈技术文档该怎么写：文档的目的应是"教"用户成为熟练使用者，而不只是罗列 API 事实。他批评把文档甩给 wiki 的做法，主张像写教程一样循序渐进地写真正的文档。
为什么经久不衰：它把"文档是教学而非说明书"这个常被忽略的原则讲得直白，十几年后仍是 API 与开源项目文档的通病诊断书。
HN 评论精选
好 API 文档的标准：每个方法配一个最小、可直接复制运行、能跑通的示例。
我最想从 API 文档里得到的，是每个方法都有一个最小可运行示例。"最小"指示例只聚焦演示这一个方法怎么调用，别的代码越少越好，这样我不用去猜哪些部分是必需的、哪些只是凑数。"可运行"指我把示例复制到单独文件里执行就能跑通——令人意外的是，很多文档都过不了这一关。面对陌生问题和陌生 API 时，最快的编程方式就是复制粘贴；文档应让复制粘贴尽可能容易。先模仿，再理解。
cousin_it查看英文原文
The most important thing I want from API documentation is that every method should have a minimal working code example. Minimal - the example should be focused on demonstrating how to call that specific method, with as little other code as possible. That way I don't have to puzzle which parts are essential and which are arbitrary. Working - if I paste the example code into a separate file and run it, it should work. Surprisingly many attempts at documentation fail this test. When we're faced with an unfamiliar problem and an unfamiliar API that can solve that problem, the quickest way of programming is copy-paste programming. The documentation should make copy-paste programming as easy as possible. Understanding comes after imitation.
wiki 大多沦为开发者甩锅的产物，只有极少数用心维护的例外。
作者说"去他的 wiki，别用 wiki，花时间写真正的文档"，我既同意又不同意。wiki 分两类：一是"我建好了，人自然会来"——不想写文档的开发者扔个 wiki 出来，让用户自己写，结果版本一更新文档就过时、错误百出，最后没人用；二是真正用心做成好站点的，但凤毛麟角，ipxe.org 算一例，估计是一个人花了大功夫做的。可惜约 95% 的技术文档 wiki 都属于第一类。
zdw查看英文原文
> "Seriously: fuck wikis. They are bad and terrible. Do not use them. Take the time and effort to write some real documentation instead." I simultaneously agree and disagree with this. Wikis fall into two categorys: 1. "If I build it, they will come", which is where the developer who doesn't want to write docs throws one up, and says "hey, all you users, document it on your own, I don't want to mess with it". Then new versions come out, things change, the docs are old/incorrect, and people get frustrated, and nobody end's up using the wiki. 2. People who actually take time to make it into a great site - these are few and far between. http://ipxe.org is one example of a well done wiki, but I'm betting that a single person spent a good deal of time doing the site. Unfortunately, it appears that 95% of the technical documentation wikis out there are in group #1, not group #2.
别在开头堆前置阅读，先把核心内容给读者，背景资料放后面。
这话题很重要，但文章开头的顺序把我绕晕了。要是每份技术文档都以"读这篇之前，你该先读另外两篇"开头，我恐怕永远没耐心等到答案。更好的做法是先讲"这是你需要知道的重点"，再补充"想了解更多背景，请读 X 和 Y"。
mathattack查看英文原文
It's a very important topic, but I have to admit the sequencing threw me for a loop. If every tech documentation that I read started with, "Before you read this post there are two other things I think you should read first" I think I'd never have the patience for an answer. Better to start with, "Here's what is important to know, if you want to understand more context, read X and Y"
并非所有用户都想成为专家，文档应只教满足其具体需求所必需的内容。
"技术文档的目的是教用户成为专家"——可也许我根本不想当专家，只想把这东西用起来。工具作者以为自己的工具重要到每个用户都得精通每个细节，这很让人沮丧。不如改成：技术文档的目的是教用户满足其特定需求所必需且足够的知识。我是程序员，一年有几次要用 Photoshop 做很简单的事，我只想尽快查到怎么画一个带渐变阴影的圆角矩形，其余一概越少越好。
7402查看英文原文
"The purpose of technical documentation is ... teach them to be an expert user of it" But maybe I don't WANT to be an expert user! Maybe I just want to USE the damn thing. It's frustrating when a tool maker thinks that their tool so important that every user must become an expert on every facet of the tool. How about, "The purpose of technical documentation is to teach the user whatever is necessary and sufficient for their particular needs." I'm a programmer. A few times a year I need to use Photoshop for something Really Simple. I want documentation that can tell me how to draw a rounded rectangle with a shaded gradient inside it (or whatever) as quickly as possible, and tells me as little as possible about anything that doesn't help do that.
历次讨论
同类还值得读
保持你的身份认同足够小
Keep Your Identity Small (2009)
Paul Graham 2009 年的一篇短文：人一旦把某个话题当成自己身份的一部分（宗教、政治、编程语言皆然），讨论就会退化成站队和争吵，因为此时争论的不再是事实，而是"我是谁…
思考与写作上首页 5 次 · 2009–2021paulgraham.com编辑精选苏格拉底式教学法：通过提问而非讲授来教学
The Socratic Method: Teaching by Asking Instead of by Telling
记录了作者用纯提问的方式，引导一群小学生从零推导出二进制计数法的课堂实验，展示了苏格拉底式教学法的惊人效果。
思考与写作上首页 5 次 · 2011–2022garlikov.com你不能说的话
What You Can't Say (2004)
Paul Graham 2004 年的经典文章，探讨那些因道德时尚而不能公开说出的观点。
思考与写作上首页 5 次 · 2014–2022paulgraham.com编辑精选龙暴君的寓言（2005）
The Fable of the Dragon-Tyrant (2005)
哲学家 Nick Bostrom 于 2005 年写的一则寓言：一条每天吞噬数千人的巨龙（隐喻死亡与衰老）长期被人类当作不可抗拒的自然规律接受，直到有人提出并最终用导弹将其杀死，…
思考与写作上首页 5 次 · 2009–2021nickbostrom.com编辑精选现实有着惊人的细节量
Reality has a surprising amount of detail (2017)
2017 年的博文指出，现实远比我们以为的充满细节：我们习惯用简化的心智模型看世界，直到真正动手做事（比如作者举的造楼梯例子）才发现处处是未曾预料的细节。
思考与写作上首页 4 次 · 2018–2025johnsalvatier.org编辑精选