技术写作与文档2020cs.tufts.edu编辑精选
用工程方法学习技术写作（2016）[pdf]
Learning technical writing using the engineering method (2016) [pdf]
导读
这篇文章介绍如何把工程方法（定义需求、做原型、测试、迭代）用到技术写作的学习上，把写作当成可拆解、可验证的工程问题，而不是等灵感降临的手艺。对写作者来说，它提供的是一套可操作的修改流程，而不是抽象的文笔建议。评论区还有一条很实用的"技术写作三阶段"框架，可以用来判断自己现在写到哪一层。
可以直接用的写作要点
- 01
把每篇技术文档当成一个工程项目：动笔前先定义读者是谁、读完要能完成什么，再决定写什么、舍弃什么。
- 02
初稿完成后找真实读者试读，观察他们在哪一段卡住、卡住的原因是缺背景还是缺步骤，据此修改，而不是凭感觉润色字句。
- 03
不要只写操作步骤，补上"为什么这样做、有哪些坑、方法的边界在哪"，这样文字才能从一次性说明书升级为值得反复阅读的材料。
- 04
版式也是内容：用标题、留白和段落长短的变化把大段文字切开，让读者愿意读下去。
HN 评论精选
技术写作分三个层次：只给步骤、讲清理由与坑、再到有见解和边界判断，后者才值得反复阅读。
即使你不读正文，这份 PDF 本身的排版也很值得一看，作者显然懂得如何设计版面、变换节奏、切分文字块，让内容更好读。我还想补充一个判断技术写作水平的三阶段框架：第一阶段只是把复现结果或操作流程的步骤列出来，读者学会之后很少再回头读；第二阶段已经做过足够多的分析和实践，写的不只是步骤，还讲清为什么这样做、要避开哪些坑、什么不该做，能引导读者想下一步；第三阶段对技术细节的讲述流畅老练到基础部分无需再论证，文中带有对过往尝试、失败原因及其技术史背景的成熟见解和玩笑，还会指出将遇到的困难和方法本身的局限，这种文字值得整个职业生涯反复重读。
supernova87a查看英文原文
I will say that even if you don't read the bulk of this link, the PDF document itself is a very visually pleasing layout, and the author clearly knows how to design, vary, and break up text to make it more interesting. It's worth a look just to see it briefly. I will just add that I can recognize good technical writing in 3 stages of sophistication: Stage 1) Someone who has barely mastered the topic and is at the most basic level just telling you the steps to reproduce the result or operate the items or workflow. Once you learn from the material presented (unless extremely complex or required to keep as reference), you rarely go back and study and appreciate this kind of writing repeatedly. Stage 2) Someone who has done the analysis and exercise enough that the writing evolves into not just instructions or rote description, but narration through the reasons why they did it this way, the pitfalls to watch out for, what not to do. Starts you thinking about what to do next. Stage 3) Someone whose telling of the technical detail is so fluid and practiced that the basics are unquestioned -- the writing now includes well-informed opinions and jokes about past attempts at the outcome, why they failed and their historical context in technical terms. Gives advice on the difficulties that will be encountered and the limits of the method. The writing is so informative that you may return to read it again and again throughout your career. One of my favorite texts that reaches Stage 3 is Numerical Recipes in C (which unfortunately I don't have much occasion to refer to nowadays), and the way that programming philosophy, advice, and technical instruction combines in that work is very impressive. Also, many of Griffiths' physics texts, who manages to write with both technical and conversational/narrative mastery. If only more writers could be like this.
推荐了另一篇关于文档分类（四种文档）的讨论，可作为延伸阅读。
这个看起来挺有意思，谢谢分享。我觉得最近另一个关于技术写作的讨论帖也很有用：《四种文档》https://news.ycombinator.com/item?id=21289832
burakemir查看英文原文
This looks quite interesting, thanks for sharing. I found the other recent thread on technical writing useful, too: Four kinds of documentation https://news.ycombinator.com/item?id=21289832
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选