技术写作与文档2011rbs0.com编辑精选
技术写作技巧
Technical Writing Tips
导读
这篇《Technical Writing Tips》是一份技术写作规则清单，涉及单位使用、精确表达和用词选择。评论区把它补成更根本的文档观：写作要围绕读者解决问题，功能说明要讲用途，别用营销术语和装腔表达。对写作者的价值在于：规则应服务于清晰沟通，而不是反过来。
可以直接用的写作要点
- 01
写技术文档先明确读者要解决的问题和目标，再决定内容和详略。
- 02
描述功能时说明它做什么、解决什么问题，不要复述功能名或营销名称。
- 03
能量化就量化并写清单位，避免含糊表达。
- 04
少用副词和装腔动词，优先用平实、直接的词；别把写作规则当绝对教条。
HN 评论精选
技术文档应围绕读者解决问题，拒绝营销堆砌，功能说明要讲用途而非复述名称。
这份指南不错，也提到我关心的点（使用单位、量化要精确）。但它漏掉任何文档的关键原则，而且是太多文档部门完全失败的：1. 给市场部一页放商标，然后礼貌或随便让他们滚开。读者可能在凌晨两点解决问题、在 CTO/CEO 注视下、或在机房热/冷通道风扇轰鸣、系统崩溃时，不会忍受一行行“Yoyodyne Tron-a-matic Blipvert Flux Capacitor Mark 5-1000[tm]”描述。用“它”“该设备”等简单代词或通用说法。2. 写作是为解决问题、达成目标。弄清问题和目标；不知道就找设计产品的工程师，更可能是懂产品、接触客户的销售工程师。他们可能最适合写文档，技术写作者应把内容纳入发布系统并核对正确性。3. 功能描述不应照搬功能名或文本，而应解释目的或作用。大量商业文档在这点上失败。
dredmorbius查看英文原文
That's not a bad guide, and it touches on a few of my pet peeves (using units, being precise in quantifications). It misses the key principles of any documentation, and one that far too many documentation departments fail utterly on: 1: Grant your marketing department one page for trademarks, and tell them as politely or otherwise as you care, to fuck off. Your customers/readers in the midst of trying to solve some problem at 2AM, and/or under the watchful eye of the CTO/CEO, and/or in a colo's hot or cold aisle with fans blaring and a melted-down stack, aren't going to tolerate your Yoyodyne Tron-a-matic Blipvert Flux Capacitor Mark 5-1000[tm] descriptions line after line. It's "it", "the device", or some other simple pronoun or generic phrase. 2: You're writing to solve a problem, to accomplish a goal. Figure out what the problem and goal are. If you don't know, get an engineer who designed the product, or more likely, a solid sales engineer who uses it and encounters customers who know the ups and downs, to straighten you out. Actually, they're the ones who're probably best off writing the docs (they probably already have), and you as a technical writer should squeeze this into your publishing system and verify correctness of the information. 3: Descriptions of features shouldn't mirror the text or name of a feature, but explain their purpose or function. The quantity of proprietary/commercial documentation which falls down on this point is staggering. 4: Document significant product bugs and failings, clearly. This is a necessary corrolary of the first principle above. The "BUGS" section of UNIX manpages were (and are) revolutionary. 5: The bulk of the style guidelines in the "Technical Writing Tips" article referenced are really niggling points of grammar and/or exposition. They're best left to a last pass through the documentation. Yes, it's helpful when the piece doesn't read like a 7th-grader better versed in SMS texting wrote it. But if you're addressing these issues before hitting the four previous points, you're rearranging the belly button lint on the deck chairs on the Titanic. It's a complete waste of time to start with, and at least three degrees removed from the real problem.
不要把 Strunk & White 当成绝对权威，写作规则可以质疑。
它建议使用 Strunk and White。我觉得有必要指出，S&W 不必被视为那么权威：http://chronicle.com/article/50-Years-of-Stupid-Grammar/25497 。Language Log 的人常对写作建议有话说。
ikirill查看英文原文
It advises using Strunk and White. I think it would be helpful to point out that S&W need not be considered all that authoritative: http://chronicle.com/article/50-Years-of-Stupid-Grammar/25497 The people behind Language Log often have something to say about writing advice.
少用副词，能删则删。
我很久前读到一条简单建议，觉得很棒：如果词以“-ly”结尾，考虑删掉它。换句话说（嘿嘿），少用副词（嘿嘿）。
latch查看英文原文
Here's a simple piece of advice I read a while ago and find great: if it ends with "ly", consider removing it. Or, put differently (teehee), use adverbs sparingly (teehee).
规则例子可能误导；真正理由是平实，不是词性；基础用词错误仍常见。
相当一部分内容像 S&W：用不诚实的例子把坏建议包装得很好。例如：避免名词作动词……别说“He authored”，说“He wrote”；别说“obsoleted”，说“made obsolete”。技术写作中不常见“to author”，不是因为“author”也是名词，而是技术写作追求平实，“to author”有点装腔。例子准确，但没说明规则。另，我希望说“affect vs. effect”对职业写作者不必要，但上周我还在旧文档里改了好几处“insure vs. ensure”。
FreakLegion查看英文原文
A fair amount of this is like Strunk & White in that it's bad advice made to look good by a disingenuous example. For instance: Avoid using nouns as verbs. [...] avoid saying "He authored ...", instead say "He wrote ...". avoid using "obsoleted", instead say "made obsolete". You won't often see the verb 'to author' in technical writing, but not because 'author' is also a noun. It's simply the case that technical writing aims at plainness, and 'to author' is a bit hoity-toity. So the example, while accurate, doesn't illustrate the intended rule. Anyway, I wish I could say that tips like 'affect vs. effect' are unnecessary for working writers, but just last week I had to fix several instances of 'insure vs. ensure' in an old document, so. Yeah.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选