技术写作与文档2016developer.com编辑精选
技术文档写作规则（2009）
Rules for Writing Technical Documentation (2009)
导读
这篇 2009 年的文章给出撰写「世界级技术文档」的七条规则，讨论语气、受众、结构等基本原则。HN 评论从实操角度补充与反驳，尤其提醒：读文档的人多半正处在出问题的焦虑中，幽默往往帮倒忙。对任何写说明性文字的人都有参考价值。
可以直接用的写作要点
- 01
把读者当成「正在出问题的人」：先设想他焦虑、时间紧、只想快速解决眼前故障，再决定详略与语气。
- 02
动笔前先明确受众是谁（新手还是专家、母语是否与文档一致），这是技术写作真正的起点。
- 03
像重构代码一样重构文档：删冗余、去铺垫，反复修改直到清楚直接。
- 04
正文里慎用幽默和玩笑，它可能显得轻佻、让读者困惑，也会给翻译和本地化添麻烦。
HN 评论精选
读者查文档时多处于危机状态，幽默帮不上忙，反而显得轻浮、易误解、难翻译。
作为技术文档作者，我对文中几点有异议。第一，「干巴巴很糟」——但幽默可能更糟。90 年代中期我所在的公司用一套 DOS 传真插件，某天它出故障大家手忙脚乱，翻出手册：总共才 10 页，最后一页全是「如何安全传真（谐音安全性行为）」的笑话。我还听说过 80 年代某政府系统出错时会在屏幕上放动画猴子，另一个程序的经典报错是「Oopie!」。幽默不该出现在文档里。我把技术文档作者看作医生、律师那样的专业人士：人们来找你，通常是在危机中——病了、被起诉了、程序跑不动了。研究显示 80% 的人只有在出问题时才查文档，所以读者多半正处在麻烦里。幽默帮不上忙，此时笑话会显得轻浮甚至冒犯；它还会造成误解，尤其当读者母语与文档语言不同时；最后，幽默让翻译和国际化更难，有些概念跨文化根本译不过去。第二点（动笔前先弄清受众）我完全同意：这是技术文档作者的真正起点。
FiddlerClamp查看英文原文
As a technical writer, I have a few quibbles with these points: 1. Dry sucks...but humorous can be worse. In the mid-90s, I worked at a company that used a DOS add-on to fax from an accounting program. One day we were in a panic because it wasn't working properly, so we dug out the manual. It was all of 10 pages, the last of which was a list of jokes about 'How to Safe Fax' (as in safe sex). Similarly, I've heard of a government system from the 80s that would display animated monkeys onscreen when an error occurred, and another program with the classic error message "Oopie!". Humor has no place in documentation. I think of technical writers like other professionals - doctors, lawyers, etc. Often, you consult a professional because you're in a crisis: you're sick, you're facing a lawsuit, or you can't get a program to work properly. Research shows that 80% of people don't refer to documentation at all until there's a problem. So when someone's reading documentation, it's a good bet they're in a crisis. Humor doesn't help. When a reader needs assistance or is in a crisis, humor can come across as silly or insulting. Humor can also confuse, especially if the reader's first language isn't the same language as the documentation. And lastly, humor makes translation and internationalization harder. Some concepts don't translate across cultures. 2a. Before you start, make sure you understand your audience. This is the key starting point for technical writers. Who is the audience for your documentation? Is it the average end-user, a developer, a system administrator, or someone else? Once you know your audience, you'll know what information they need spelled out and what they already understand. You'll also know what they'll be looking to achieve, and how you can write documentation to help them meet their goals. 5a. Use illustrations only when necessary. Illustrations and diagrams can be costly to create, update, and translate. Don't use them when a list or table would do the job. I would add the following two points: 8. For longer documentation, always include a revision table at the beginning of the document. This helps readers (and writers who may update your materials in the future) to understand what changes have occurred. 9. Identify external hyperlinks that do not link to URLs. For example, I would write a hyperlink to a PDF as <hyperlink> (PDF, 3.6MB). This provides the reader with a preview of what they can expect to find.
好文档像好代码：简洁直接，靠反复重构打磨清楚。
和代码一样，好文档应当简洁直接。不断重构你的文档，直到它足够清楚。
nickpeterson查看英文原文
Much like code, good documentation is concise and direct. Refactor your documentation until it's clear.
可对照阅读一篇「反面教材」：怎样写出看着漂亮、实则糟糕的文档。
反过来的版本：《如何写出看起来很好、实则很糟的文档》（kuro5hin 旧文存档链接）。
davidgerard查看英文原文
the opposite: HOWTO: write bad documentation that looks good http://thelaird.us/k5/section-slurp/k5-tech/2003-9-29-104212-112.html (archived from kuro5hin)
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选