技术写作与文档2009jacobian.org编辑精选
编写优秀文档：技术文风
Writing great documentation: technical style
导读
这篇讲技术文档的写作风格：如何让文档清晰、可扫读、可执行，并用强调、链接和示例降低读者负担。对写作者来说，它提醒我们技术写作不只是把话写短，还要管理注意力、语气和可操作性。
可以直接用的写作要点
- 01
删减冗词要适度：句子都清楚但通篇过度压缩会让读者更累，适当留白反而更易读。
- 02
避免在操作说明里用“只需/很简单”这类词，读者失败时会感到被冒犯。
- 03
用强调和折叠/隐藏样板代码来聚焦关键片段，而不是让读者在无关细节里找重点。
- 04
为每个章节设置可引用的锚点，并在正文中多用内联链接，方便读者跳读和溯源。
HN 评论精选
技术文档可以把示例做成可运行/实时演示，并用折叠隐藏样板代码，减少读者负担。
总的来说这是一篇很棒的文章。我想补充一点：与大多数报纸文章不同，技术文档可以是“可执行”的。意识到这一点时我兴奋得差点要坐下。我在 A/Bingo 的文档里做了一些尝试：文档以实时演示呈现，格式化后的示例代码由我实际运行的代码自动生成，因此会自动更新，我不必额外维护；我还大量使用喜欢的 JavaScript 效果让呈现比线性文字更流畅。比如技术文档常要把注意力集中在一堆样板代码中的某一段。你可以把要强调的部分加粗，也可以用 JavaScript 隐藏无聊细节，只让需要的人展开查看。我认为这比链接到另一页的完整版本更好，因为更少打断读者的流程；也比在样板代码里塞几行加粗文字更易读，比省略样板代码、给出复制后跑不起来的代码更可用。
patio11查看英文原文
This is, in general, an awesome article. The one thing I'd add is that, unlike most newspaper articles, technical documentation can be executable. I was so excited when I realized the implications of that I nearly had to sit down. (Yes, I live a boring life.) I did a bit of that with the documentation to A/Bingo: the documentation is presented in a live demo, the formatted sample code is automatically composed from what I'm actually running (and thus gets automatically patched without me having to do anything special about it), and I copiously abuse my favorite Javascript effects (lightboxes, etc) to make the presentation flow better that linear text. For example, often in tech documentation you want to focus attention on a portion of the code buried in a bunch of boilerplate. (Or maybe that is just those of us who write Java all day.) You can bold the bits you want to emphasize, or you can hide the boring details with Javascript and let only those folks who need them look them up. My opinion is this is better than linking to a fuller version on another page, as it interrupts the user's flow less. It is also more readable than a few lines of bold text studded in the boilerplate, and more usable than omitting the boilerplate and producing code which doesn't function if copy/pasted.
技术文档要给每节锚点并多用内联链接；强调标签要慎用。
我很惊讶你没强调：每个章节都应有可引用的锚点，并在正文中大量使用内联链接——不只是明显的锚链接，还包括像早年 Suck.com 那样散在正文里的三级链接。小挑剔：把逗号分号放在引号内并非必要，别用外部标点污染引文；另外，默认样式的 em/strong 不如直接用 i/b，别为了模仿 Jakob Nielsen 而滥用加粗。
blasdel查看英文原文
I'm really surprised you didn't stress the importance of having useful fragment identifiers for every section, and using references to them liberally -- and not just the obvious <a href="#foo">foo</a> -- tertiary links inline in prose like Suck.com popularized in the olden times. Some nitpicks: and you need to understand why I’m putting the commas and semicolons in this sentence inside the quotes, not outside I know why you do that, but it doesn't make it any less bullshit. It's not like you're doublestriking on a monospaced typewriter or manually kerning on a press! Don't pollute what are ostensibly quotes with exterior punctuation. At least you're using the oxford comma :) Mostly, this means using emphasis and strong text frequently. I usually avoid too much strong because it’s looks like I’m just aping Jakob Neilsen, but whatever. An apter and and more pejorative example for today's whippersnapper would be Jeff Atwood. In my opinion using <em> and <strong> with default styles is worse than useless, just use <i> and <b>, they aren't poisonous. I did appreciate the <em> as yellow-highliter fad that 37signals kicked off years ago.
删除“只需/很简单”等可能显得居高临下的词。
我在技术写作里有一个坏习惯：在操作说明前加副词“simply（只需/很简单）”。职业生涯早期有人指出，这比噪音还糟：如果读者没成功，或根本不觉得简单，会感到沮丧或被冒犯。我现在总会第二遍通读，删掉任何可能显得居高临下的措辞。
Adrock查看英文原文
One written tic I have in my technical writing is to use the adverb "simply" before an instruction. It was pointed out to me early in my career that this is worse than noise... it can make the reader feel bad or annoyed if they don't succeed or perceive it as simple. I now always make a second pass to remove any potentially condescing phrases.
“删减冗词”不能机械执行，适当留白和句子长度让文档更易读。
我想谈谈“删减冗词”这条规则。总体上我同意，但如果整篇文章严格执行，我会觉得很难读，尽管每句都逻辑清楚。它需要更高专注力，比如这篇文章就读得我很累（英语不是我的母语）。我更喜欢 Mark Pilgrim 的 diveinto____ 风格，文字更有“空间”、更轻盈。我的看法是，句子并非总是越短越好。
greyman查看英文原文
I'd like to comment the rule of "omit needless words". Generally I agree with that, but if it is applied rigorously across the whole article, I find it quite difficult to read, despite each sentence being logical and clear. It just needs a greater concentration then, like in this very article - I was tired after reading it (English is not my mother language). I prefer Mark Pilgrim's diveinto____ style, where the text has more "space" and feels lighter. In my opinion, it is not always better to make the sentence shorter.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选