技术写作与文档2021kislayverma.com编辑精选
程序员为什么不写文档
Why programmers don’t write documentation
导读
这是一篇讨论程序员为何不写文档的文章，评论区的讨论则集中在：写文档本身就是一项需要练习的技能，它考验同理心与条理；文档要区分读者对象；甚至要像测试代码一样测试文档。对写作者而言，这组讨论把“为读者而写”和“如何验证写作有效”讲得很具体，可以直接迁移到技术写作与说明性文章上。
可以直接用的写作要点
- 01
把文档写作当成一项需要刻意练习的技能，而不是写完代码后顺手做的杂活；愿意在表达上花时间，本身就是专业度的一部分。
- 02
动笔前先明确读者是谁：非技术同事、外部使用者，还是接手代码的同侪，不同读者需要完全不同的详略与语气。
- 03
与其写“巧妙”却没人看得懂的代码和文档，不如把聪明用在降低读者的理解成本上——写作需要同理心和组织能力。
- 04
写完后要像测试代码一样测试文档：找不熟悉项目的人来读，看它能否回答新人真正会问的问题，否则不能算完成。
HN 评论精选
文档写作是需要练习的技能，缺文档会让知识变成口口相传的“部落知识”，不肯写文档甚至被当成骄傲，这是很荒唐的。
文档写作是一门技能，和其他技能一样需要练习。作者说自己进了一家大厂，发现那里文档糟糕透顶：所有人只管写“聪明”的代码，连注释都懒得写，于是 wiki 一片混乱——想学怎么用某个队列、想知道某个场景该用哪个数据库、想新建一个接口，全都只能靠口口相传的“部落知识”。更糟的是，入职培训上有个扎马尾的“10 倍工程师”说：“你要是私信问我问题，我就没法帮到其他人了。”作者当时没胆量反问：那你的文档为什么这么烂？似乎还有人因为别人必须私信他才能看懂他的代码而感到自豪。结论是：别再把精力花在炫技的代码上，把学新语言、试新技术的劲头拿去练写作；写作需要同理心、条理和技巧，它会让你的代码更好，也会让你成为更好的人。
KaiserPro查看英文原文
Documentation is a skill. Like any skill it takes practice. I have moved to a FAANG and their documentation is downright fucking awful. _everyone_ just writes code, with lots of "clever" bits, and doesn't bother to fucking comment. Not only that because people don't even _comment_ their code, the wiki is a total shit show. Want to know how to use a Queue? tribal knowledge. want to know which DB is best for x? tribal knowledge. Want to know how to create a new endpoint? tribal knowledge. Worse still, we had a class during induction where some ponytailed "10x" said "If you are messaging me asking questions, I can't help other people" I didn't have the bollocks at the time to ask why his documentation sucked arse. There seemed to be a weird pride in the fact that people needed to message him to figure his shit code. The moral of the story is this: fuck off with your clever code, spend that effortyou put into learning new languages, or trying a new techniques and put it into developing your writing skills. It takes empathy, organisation and skill. It'll make you a better programmer and a better person.
视频可以替代部分文档：录得快、能边演示边讲解、利于新人自学；但简明操作指南仍需文字文档。
作者在游戏行业，视觉化需求促使他们把大量内容做成视频：既用于 PR 说明，也用作大部分“文档”。他本来偏爱阅读，对什么内容都搬到 YouTube 上一度很反感，但后来被说服了：一是快，半小时就能录一个深入讲解的视频，而写文档要花几小时打磨，代码变了就丢掉旧视频再录半小时；二是可以一边演示代码的运行效果一边讲解，相当于给代码库配了一系列讲座而不是教科书；三是对新人上手复杂模块特别有效，几千个 PR 里九成都有视频说明，新人可以自学，不必占用其他工程师的时间，这对跨 12 个时区的团队尤其有用。当然这不是万能药，需要给其他团队提供简明“操作指南”时，他们仍然保留文字文档。
hesdeadjim查看英文原文
I’m in games so the visual element often forces this, but I’ve moved our team to making a lot of video content, both for PRs and for much of our “documentation”. I’ve always preferred reading, and the trend to everything being on YouTube has driven me nuts, but I’m a convert to this method for a few reasons. First, it’s fast. I can sit down and make a deep dive video in 30 minutes and not have to sit around writing and polishing documentation for hours. When the code inevitably changes, I can throw away the old video and spend another thirty minutes making a new one. Second, I can demonstrate what the code does while offering instruction around it. If I likened it to anything, it’s like having a series of lectures to your code base rather than a textbook. And lastly, it’s proven GREAT for on boarding a new engineer in the more complex aspects of the project. Because they can go and view thousands of PRs, 90% of which have video demonstrations or explanations, they can do a lot of self directed learning and not require nearly as much over the shoulder time with other engineers. When your team is spread across 12 hours of time zones, this is very useful. This method isn’t a panacea, and we still keep written documentation when we need to provide a concise set of “how to’s” to other teams. But for the dev team, it’s been great.
写文档前先分清读者：非技术同事、技术用户、同项目开发者、第三方用户，各有不同的内容重点和详略。
作者认为原文忽略了一个重点：文档要写给谁看。二十年经验下来，文档几乎必不可少，但针对不同读者写文档本身就是一门技能。一、内部非技术用户：这段代码做什么、为什么写、现在谁负责、什么时候运行、怎么运行、出错怎么办，越简明直接越好。二、技术用户：就是那份不必频繁更新的 README，说明代码用途、安装或加载的快速上手步骤、依赖，以及最基本的一组函数和参数。三、同项目的实现者：在上述 README 之外补充代码的高层结构划分，以及常用功能该去哪里找，这时带注释的代码最有用。他认为最好的注释通常是两类：一是“注意：这里为什么这么写，是有原因的，没看懂之前别急着改”；二是“将来如果要做 X，你需要做 J、K、L，并更新 M”。这类注释替他省了大量时间和麻烦。四、第三方用户：这才是真正的大工程，值得配专职技术写作者，那是另一套技能。
massung查看英文原文
Something the author didn't dive into - which is very important - is the audience of said documentation. In my 20+ years documentation is pretty much essential, but there is definitely a skill in documenting for a particular audience: * Internal, non-technical users; what does the code do, why was it written, who currently owns it, when should it be run, how to run it, and what to do in case of failure. The more accessible, brief, and direct the better. * Technical users; this is your README that usually doesn't need to be updated all that often. What is this code for? A quickstart for install/loading, dependencies, and the bare-bones set of functions, arguments, etc. * Fellow implementers; the above README, but likely with a few additional notes of how the code is (high-level) broken up, and where to go for the most common things. This is where documented code is really good as well. I usually find the best code comments have always been A) NB: here's a drawn-out explanation of why the code does this, it's for a reason, do not question the code first unless you understand this and/or the above reason has changed, and B) in the future, you may want to do X, in which case you'll need to do J, K, and L and update M. Comments like those have saved me (from myself, even) so much grief and time. * 3rd party users; this is where real documentation gets to be a monumental PITA and any company worth its salt will hire a technical writer or two. This is a very different skill than what's required for any of the above. The biggest concern I see brought up again and again with documentation is that it becomes out of date quickly as soon as it's finished being written. This needn't be true. Internal documentation is just enough info for whoever is using it to know what it is, how/when to use it, what to do if it fails, and who to go to for more information or help. Honestly though, the biggest problem with documentation has always been where it lives and how it's edited. Is it all repo READMEs and markdown? Are they google docs? A wiki/confluence? This is always where the breakdown happens. Programmers are comfortable with just being pointed to a repo and text files, while non-programmers want WYSIWYG docs somewhere central, which is the last place most programmers even think about. Wikis/confluence attempts to be a compromise that (IMO) no one likes. This - like task tracking - is a unicorn of software development.
文档也需要像软件一样做可用性测试：找人验证它能否回答新手的问题，否则大量文档只是列了参数却无法使用。
有很多评论说文档其实不难，作者反问一句：你们怎么测试文档？是真正去测——确认它能回答新手的各种问题，而这些新手并没有在这个项目上干了几个月？如果不测试，凭什么认为文档写完了？你会这样对待软件吗？他见到的绝大多数文档都有问题，最常见的是重要主题或情形缺乏覆盖，而且他说的还不是“这个产品为什么这样设计”这种内容，而是：某个 API 提供了各种操作 Fribbler 的方法，可 Fribbler 类的说明只有一句“这是代表 Fribbler 的主要类”，读者完全不知道它是什么、在整套 API 里处于什么位置；参数或属性只是列在那里，不解释含义，甚至根本没列出来，却又在别处冒出来——“除非你给 Fribbler 构造函数传了 borgle 属性，否则这个方法会异步执行”，读者心想：居然还有个 borgle 属性？而这些还只是最基本的使用说明，想参与贡献、跑测试就更什么都没有了。文档需要可用性测试。
yoz查看英文原文
There are a remarkable number of commenters saying no, documentation isn't hard actually. One question for those commenters: How do you test your documentation? Properly test it, ensuring that it answers many kinds of questions for those who are new to the topic, and who haven't already been working on this project for months? If you're not testing it, then how can you consider it done? Would you do the same with your software? The vast majority of documentation that I see these days is bad in multiple ways. Most common is lack of coverage for important topics or cases, and I'm not even talking about things like "why this product is built this way". I'm talking about stuff like: - An API providing all kinds of methods for manipulating "Fribblers", and when you look at the Fribbler class it just says "This is the primary class representing Fribblers." No idea what this means or how it fits into the wider API? Good luck! - Parameters or properties appearing in lists without any explanation of what they mean - ... and that's assuming those parameters are even listed at all, which (often) they're not - ... especially when those parameters appear in other parts of the documentation. "This method will work asynchronously unless you've passed the "borgle" attribute to the Fribbler constructor." There's a borgle attribute?! - And this is all just for basic usage of a product. Want to contribute, or run tests, or anything else? Nothing. Documentation needs usability tests, same as anything else which is primarily designed to be used by humans who may not have seen it before. But it's hard enough getting proper UX testing for the product, let alone its documentation.
同类还值得读
编写更好文档的框架
A Framework for Writing Better Documentation
这是 Divio 的文档写作框架，把技术文档按「读者的目标」分成四类：教程（学习导向）、操作指南（问题导向）、参考（信息导向）、解释（理解导向）。
技术写作与文档2021 · 637 分 · 76 评4 条写作要点编辑精选写好一份设计文档
Writing a good design document
这篇 HN 帖子标题为《Writing a good design document》，主题是如何写好一份设计文档；对写作者来说，它值得作为技术写作和结构化说明文的参照。
技术写作与文档2025 · 581 分 · 147 评3 条写作要点编辑精选技术写作课程
Technical Writing Courses
这是 Google 官方免费技术写作课程（两门），讲受众定义、主动语态、短句、文档结构等基础方法。
技术写作与文档2020 · 571 分 · 73 评4 条写作要点编辑精选写出更好的错误信息
Write better error messages
这篇帖子讨论如何写出更好的错误信息，评论补充了开发者场景下的具体做法和真实反面案例。
技术写作与文档2022 · 566 分 · 253 评4 条写作要点编辑精选写一本技术书的经济账
The Economics of Writing a Technical Book
一位技术书作者拆解写书的真实经济账：版税收入往往远低于投入的时间成本。
技术写作与文档2018 · 519 分 · 149 评4 条写作要点编辑精选