技术写作与文档2022reproof.app编辑精选
先写文档，再动手开发
Write documentation first, then build
导读
这篇博文主张「先写文档再动手实现」，把文档当作产品设计的先行稿。但评论区几条高赞回复提出了有力反驳：文中举的 VisiCalc、Nest 案例被指与史实不符，而「文档要写到什么程度、什么时候写」才是真正的分歧点。对写作者来说值得一读，因为它逼你思考：先写清楚在什么阶段、以什么粒度才真正有用。
可以直接用的写作要点
- 01
先写「骨架」而不是「全书」：先列出目标与关键特性的提纲，等产品定型后再补细节，避免写完就过时。
- 02
引用案例前先核实：读者当场指出文中 VisiCalc、Nest 的例子与事实相反，论据一倒，整篇文章的可信度也会跟着受损。
- 03
过时的文档比没有文档更有害——它会破坏读者信任，所以宁可写短、写可改，并及时更新或删掉。
- 04
把写作量控制在能快速看到成效的最小范围，靠反馈维持写作动力，别让重复劳动消耗热情。
HN 评论精选
即兴动手更能保住动机，提前写完整文档往往与成品脱节。
说不好。我开新项目往往是即兴的：有个想试的点子就直接动手。一边写代码打基础，一边考虑长远。先写文档、再在代码里重做一遍是双倍工作，极其低效，而动机很重要，重复并不有趣。大多数项目根本做不完，障碍总会有、有些还很难，光靠写文档你根本发现不了。而且提前写的文档很可能在第一版发布时就不符合最终产品了。有个包含关键特性的总体提纲没问题，但完整详尽的文档就过头了。这是我的一家之言：对单打独斗的开发者来说动机尤其重要，何况你可能好几年都不知道这东西有没有人用。如果有专人分工，情况大概不同。另外，不能拿成功企业反推说它们成功就是因为有份备忘录或文档，这太牵强了。
lakomen查看英文原文
I don't know... When I start something new it's often spontaneous. I have this idea I'd like to try and then I start hacking. And while I hack at the keyboard and create the basis I think of the long term. Having to do double work, write a document first and then repeat the same in code is extremely counterproductive. Motivation plays a big role. Repetition is not fun. Most projects never get finished. There are always obstacles and some are really hard. But you won't know them from writing documentation alone. And if you write documentation ahead of time it's very likely this documentation will not fit the final product, at 1st release time. Having a general outline with key features is ok. But fully-fledged documentation is over the top. That's my educated opinion at least. Motivation is very important for me, especially if I don't know for years if this thing I'm building will be used by people at all. Single developer. If there were dedicated people for tasks, that'd be different, probably. Also you can't take the established business and say they all had a memo or document and that's the reason why they succeeded. That's a really long shot, IMHO.
文章开篇两个案例经不起核查，实际都是产品先行、文档在后。
「VisiCalc 起于一页参考卡」似乎是假的。有资料说，他们是——如果某个功能没法在参考卡上解释清楚，就改代码，所以是代码在先。「Nest 温控器起于一份新闻稿」也不对：据我所知，产品是在一篇有可演示产品的 Verge 文章里公布的，成功秘诀是设计者做过手机。两例中真正的产品文档都是最后才有的，正如我们预料。所以文章一开头就是两记胡扯的重拳——好在他们至少把胡扯写下来了。
drewcoo查看英文原文
> VisiCalc started as a reference card. That appears to be false. This [1] tells how if they couldn't explain the feature on the reference card, they'd change the code. So the code came first. > The Nest thermostat started as a press release. From what I can tell, the product was announced in a Verge article[2] where there is a demo-able product. And the secret to their success, according to the article, was that it was designed by people who'd worked on phones. From what I can tell, actual product documentation came last in both cases, exactly as we'd expect. So the article starts with a double-barrel blast of bullshit. In the article's favor, they did write the bullshit down, though. [1] https://landley.net/history/mirror/apple2/implementingvisicalc.html [2] https://www.theverge.com/2011/11/14/2559567/tony-fadell-nest-learning-thermostat
「先想再做」是老做法而非新主张，被污名化没有道理。
绕了一圈又回到原点。2005 年我开始做职业软件开发时，行业就是这么建软件的，而做充分分析（业务、技术）的想法还更早。会觉得惊讶的，只有那些把「敏捷这碗汤」喝多了的人。我不是要黑敏捷、重开骂战（敏捷有它的价值），只是「先想再做」最近不知为何被污名化了。就像软件开发被困在马达加斯加系列里朱利安国王的脑子里：先干起来再说，别管它到底有没有意义。
brzezmac查看英文原文
So we have come full circle. That's the way we have been building software when I was starting with professional software development (this was around 2005). But the idea of doing a thorough analysis (business, technical) is a little bit older. The only people to whom this might come as a surprise are the ones who've drank too much of the "agile Kool-aid". I'm not here to bash agile and start this flame war all over again (agile has it's merits ...), but somehow thinking before doing got a bad rap recently (for reasons beyond me). It's like software development got trapped inside of King Julian's (from Madagascar movies/series) brain with his modus operandi: "let's start doing this before we figure out it does not make any sense".
文档宜做成可改的骨架、随产品演化；过早完成不如晚成。
文档应该从容易修改的粗糙骨架起步，随着产品逐渐定型再填充。因为系统在构建过程中会演化，一边演化一边不停同步文档，是件容易出错又烦人的苦差，不是人人都有耐心和勤勉。既然系统会随构建而演化，那么文档过早「完成」，最终准确度反而低于晚完成的版本。过时的文档常常有害且打击士气，因为它们破坏信任。
daenz查看英文原文
Docs should start out as a rough scaffolding that is easy to change, then filled in as the product anneals. The reason is that systems evolve as you build them, and constantly updating the docs to be consistent as the evolution occurs is an error prone chore that not everyone has the patience or diligence for. Assuming that your systems evolve as you create them, if you "complete" your docs too soon, you end up with less accurate docs than if you complete them later. Out of date docs are often harmful and demoralizing because they break trust.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选