技术写作与文档2014americanscientist.org编辑精选
科学写作的科学
The Science of Scientific Writing
导读
这篇经典文章讨论科学写作如何让读者更省力地理解信息，重点比较表格与句子在信息组织上的差异，并强调按读者预期排列变量和关系。对写作者来说，它提醒我们：清晰不是简化内容，而是降低读者提取关系的认知成本。
可以直接用的写作要点
- 01
把相关信息按语义分组呈现，别让读者在无关信息里费力筛选。
- 02
先交代自变量及其变化，再解释因变量或结果，符合读者理解关系的顺序。
- 03
可读性不取决于读者是否“熟悉”，而取决于信息排列是否便于快速提取关系。
- 04
面向专业读者也别把复杂当成高级，科学家也是人，清晰简洁同样有效。
HN 评论精选
表格易读来自空间语义分组和变量顺序，不是熟悉度；应按自变量组织信息。
扫读第一部分，他们的方向对，但理由错了。表格比句子易读，是因为变量在空间上按语义分组：先看第一列，看到单调递增的时间，再直接解读第二列数字。句子中则要先过滤很多干扰信息，才能理解或确认自变量的基本模式；他们还把句中项目顺序弄混，增加了干扰。关键不是“熟悉”，而是提取相关信息的难易；如果句子有序而表格无序，视数据而定，句子也可能更易读。第二张表不常规：它按自变量排序，却把因变量放在前面。若惯例是把自变量放右边，这张表就完全熟悉可读。理由不是“重要信息是温度”，而是表格按自变量排序——我们需要知道自变量是什么、如何变化，才能更容易看出因变量与它的关系。
vacri查看英文原文
Scanning through the first section, they've got the right idea, but the wrong rationale. The reason why the table is easier to read than the sentence is the spatial semantic grouping of variables. You scan the first column, see the monotonically increasing time, then can directly interpret the numbers in the second column. In the sentence, you have to filter out a lot of chaff before you can understand (or confirm) the basic pattern in the independent variable. They also mixed up the order of the items in the sentence, making for more 'chaff' obscuring analysis It's not about 'familiarity', but the ease of pulling related information - if the sentence was ordered but the table unordered, then depending on the data, the sentence could be easier to interpret, for example. The second table is unconventional - it is ordered by the independent variable, but it leads with the dependent variable. If we had the convention of putting the independent variable on the right, this table would be perfectly familiar and readable. The rationale isn't "the important information is the temperature", as the article says, but that the table is ordered by the independent variable - we need to know what it is and how it behaves, then we can more easily the relation of the independent variable against it.
专业读者也首先是人，别把复杂表达或界面当成科学家的偏好。
我有个客户做面向科学家的网站。她坚持认为科学家更喜欢她那套复杂的导航，而不是标准、干净、简单的导航。我总说“但科学家也是人”，却没人听。很沮丧。
SimpleXYZ查看英文原文
I have a client with a website that targets scientists. She insists scientists prefer her complex navigational "whatever you call her crazy thing" to a standard, clean, and simple navigation. I keep coming back with "but scientists are people" and it falls on deaf ears. It's so frustrating...
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选