技术写作与文档2020mkaz.blog编辑精选
技术写作笔记
Notes on Technical Writing
导读
这是一篇关于技术写作的读书笔记式文章，梳理了技术写作这一领域的定义与要点。评论区最有价值的补充是：真正让读者抓狂的往往不是文风，而是跑不通的代码示例和含糊不清的开头；写作者应先明确读者是谁、想达成什么，再动笔。对写作者来说，这篇的价值在于它把「风格」与「可用性」的优先级摆到了一起比较。
可以直接用的写作要点
- 01
动笔前先回答两个问题：读者为什么读、读完后能做成什么；答不出来，写出来的东西多半会被认为无关或平庸。
- 02
开篇直接说明这篇要讲什么，不要用大段「我为什么写这篇」铺垫——读者很忙，会直接关掉页面。
- 03
示例代码要能直接跑通、写出完整导入，最好配有自动化测试；风格再完美、代码跑不起来，读者只会沮丧。
- 04
别把精力耗在标题大小写这类风格争论上（有人为此开了三小时会），把时间投给准确性和可验证性。
HN 评论精选
文档的价值在准确、可运行，而非文风；代码示例应完整并自动化验证。
很多技术写作者把注意力放在文风上，我见过团队为标题大小写开了三场一小时的会。我更希望他们把精力放到别处：没真正跑通的东西就别写文档，光靠问工程师不够，文档会明显缺乏深度和精确性；代码示例要写完整的导入，在有依赖环境的机器上连外行都能照着做；给代码示例建自动化测试；把「缺文档」定为发布的阻塞项。文风完美、代码却一个都跑不起来、我还要花半小时补那些「显而易见」的部分，这才是我真正恼火的时候。我不记得曾因为文风差或句子长而对文档失望过。
BossingAround查看英文原文
A lot of technical writers focus on the style of the text. For example, I've seen tech writers have long discussions (more than 3 hour-long meetings) about title capitalization in our organization. I wish tech writers would channel their focus elsewhere: - If you haven't got it working, don't document it. Getting information by talking to SWEs is not enough. Your docs will lack depth and preciseness, and it will show. A lot. - Show fully qualified imports in code samples. If you don't know what that is, ask SWEs. Given a computer with installed dependencies (such as Maven, Pip, npm, etc.), even your (grand)mother should be able to follow the docs. - Create automated testsuide for your code samples. - Mandate that lack of docs be a blocker for a release. When there are docs written in perfect style and English, yet none of the code samples works, or when I have to spend 30 minutes finishing the "obvious" parts of the code to get it to work, that's when I get really frustrated. The article seems to be deeply focused on the style. I can't remember when I got frustrated with documentation because the style was bad, or because the sentences were too long.
开篇就交代内容主旨是对忙碌读者的礼貌，别用自我铺垫清嗓子。
作者先说写这些笔记是为了帮自己思考和记住，后面又说「你不需要告诉读者你将要讲什么，直接讲就行」，这两处有点矛盾。任何非虚构写作，如果开头没让我清楚知道内容是什么，可能就过不了我的筛选，长篇报道里尤其常见；作者在开头两段大谈自己的挣扎和抱负时也是这样。在第一段就告诉读者接下来要读什么，是一种礼貌：大家都很忙，没时间熬过开头的清嗓子，他们会直接关掉标签页。
aazaa查看英文原文
> In this time, I’ve read various resources on technical writing and documentation. These are my notes, both to help me remember later, but also as a tool to help me think about writing now. and later, in an apparent contradiction ... > You don’t need to tell the reader what you’re going to tell them. Just tell them. I think this point could be fleshed out better. Any piece of nonfiction writing, technical or otherwise, that doesn't give me a clear idea about its content may not pass my filter. I see this the most in long-form journalism. But it also pops up when authors focus on themselves, their struggles, and their aspirations in the first couple of paragraphs. Telling the reader what they're about to read in the first paragraph of a technical piece is a courtesy. People are busy, and they don't have time to wade through a bunch of throat-clearing at the start of a piece. They'll just close the tab and move on.
写作前先界定读者的目的与期望收益，否则内容会被视为无关或平庸。
我总是在动笔前先弄清读者：他们为什么读，读完之后希望能做得更好的是什么，或者要据此做什么决定。作者如果答不上这些问题，写出来的东西很可能被认为无关、错误，或者只是「还行」。写技术报告时这一点比写文档更关键。
KineticLensman查看英文原文
I always try to understand the readers before writing a word. Why they are reading. And what they expect to be able to do better as a result of reading, or what decision they might be making. If an author can't answer these questions, they will likely write something that is perceived as irrelevant, wrong, or simply 'meh'. This is especially true when writing 'technical reports' as opposed to 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 条写作要点编辑精选