技术写作与文档2017dev.to编辑精选
如何应对技术写作
Tackling Technical Writing
导读
这篇帖子讨论技术写作，核心观点是：技术写作的目标不只是“被理解”，而是“避免误解”，因此一致性和清晰度至关重要。评论还强调不要假设读者拥有和你相同的背景知识，并解释“怎么做”背后的“为什么”。对写作者来说，这些原则可直接用于教程、文档和知识型文章。
可以直接用的写作要点
- 01
把“避免误解”作为技术写作的首要目标，检查每个可能被误读的表述。
- 02
全文保持术语和表达一致，优先用清晰、具体的句子，而不是含糊的概括。
- 03
不要默认读者拥有和你相同的背景知识，必要处补充定义和上下文。
- 04
不仅写清“怎么做”，也解释“为什么”，帮助读者建立理解而非机械照做。
HN 评论精选
技术写作应以避免误解为目标，靠一致、清晰和解释原因来建立读者理解。
我最喜欢的技术写作建议之一来自与 Owen Linzmayer（《Apple Confidential》作者，No Starch Press）的邮件交流：“技术写作最重要的一点是，目标不一定是被理解，而是避免误解。因此，一致性和清晰度至关重要，你永远不应假设读者拥有你所具备的知识。”“我尽量不仅告诉读者如何做某事，还要告诉他们为什么。这样他们就不只是照着说明、机械地学习，而是在建立对你所解释系统的理解，甚至可能想出你没覆盖到的解决方案。”
mcone查看英文原文
One of my favorite tech writing tips came from an email exchange with Owen Linzmayer, the author of Apple Confidential (No Starch Press): "The most important thing to remember about technical writing is that the goal is not necessarily to be understood, but rather to avoid misunderstanding. As such, consistency and clarity are paramount, and you should never assume your reader has the knowledge you possess. "I try to make sure to tell readers not only how to do something, but why. That way they are not just following instructions and learning by rote, but rather, they're building their understanding of the system you're explaining, and perhaps can devise solutions to problems you haven't covered."
提出被动语态习惯难改，并质疑主动语态是否总优于被动语态。
一位同事反馈我写作中应避免被动语态。我不确定自己怎么养成被动语态习惯（也许是化学 101 实验报告？），但一直很难改。主动语态总是更好吗？
criddell查看英文原文
I received some feedback from a coworker about some of my writing to avoid the passive voice. I'm not sure where I developed my passive voice habit (maybe in my Chem 101 lab reports?) but it's been a hard one to break. Is active voice always better?
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选