技术写作与文档2010engineerwriting.jottit.com编辑精选
我看过的最好的工程师写作建议
Best Writing Advice for Engineers I've Ever Seen.
导读
这是一篇给工程师的写作建议文章，核心是让技术写作更简洁、更有信息量。对写作者的价值在于：它把"简洁"从空泛的口号落到可操作的层面——段落如何衔接、句子如何具体、读者如何被带着往下读，而评论区还补充了新闻写作式"快速高效传达事实"的视角。
可以直接用的写作要点
- 01
让每一段的结尾都把读者引向下一段，制造"我还想知道更多"的牵引力，而不是把话一次说尽。
- 02
把信息写得具体可感：与其说"我们提出了一种新抽象来改进软件开发"，不如说清用了什么方法、解决了哪个具体问题。
- 03
简洁不等于信息稀薄，短句若只说空话反而更糟；先保证有实质内容，再压缩表达。
- 04
给 hurried reader 写作：假设读者时间紧张，把事实按重要性快速、高效地送到他眼前。
HN 评论精选
段落结尾要牵引读者往下读；同时作者自己就该先做到句子正确、长短得当。
写书时 O'Reilly 寄给我一本 William Zinsser 的《On Writing Well》，我通读后觉得很值。他最好的建议之一是：每一段的结尾都要把读者引向下一段，让读者想要知道更多。有点讽刺的是，所链接文章的第一句语法就是错的："How to make engineers write concisely with sentences?" 加了问号却并不是一个问句；第二句又太长，靠三个逗号给读者喘息空间。
jgrahamc查看英文原文
When I was working on my book O'Reilly sent me a copy of "On Writing Well" by William Zinsser (http://www.amazon.com/Writing-Well-Classic-Guide-Nonfiction/dp/0062735233). I read the entire book and I thought it was well worth it. One of his best pieces of advice is to end each paragraph leading the reader to the next one; the reader should want to know more. It's slightly amusing that the first sentence of the linked article is grammatically incorrect: "How to make engineers write concisely with sentences?" is not a question despite the question mark. The second sentence is overly long and uses three commas to give the reader breathing space.
对工程师最有用的写作训练是新闻式写作：为匆忙读者高效传递事实。
新闻课是我高中上过的唯一有价值的"语言艺术"课。那些"文学"课在我看来多半是胡扯、浪费时间——说得直白点。有些课和老师我事后回想会更有好感，因为发现它们对我有益，但文学课没有一个属于这一类，只有新闻课留给我"有用"的印象。为什么？因为文学课是就老师对某本（多半也是胡扯的）书/文章/剧本的胡扯解读写胡扯；而新闻课教的是如何快速高效地把事实传达给一个匆忙的读者。
davidw查看英文原文
Journalism class was the only worthwhile "language arts" class I took in high school. The "literature" ones were, IMO, mostly a bunch of horse shit and a waste of time, to put it very bluntly. There are classes and teachers that I looked back on more fondly when I was done with them because I realized they'd been good for me even if they were difficult, but none of the literature ones were in that category, only the journalism class stuck with me as something useful. Why? Because the lit ones were about writing bullshit about some teacher's bullshit interpretation of what was more often than not some sort of bullshit book/essay/play/whatever, whereas the journalism class was about how to convey facts to a hurried reader quickly and efficiently. Ok... rant over:-)
简洁必须建立在具体信息上，空洞的概括再短也没价值。
另一件重要的事是：让你的信息具体、明确。开头写"我们创造了一种新颖的抽象来改进软件开发"是没用的——它确实简洁，但什么也没说。而"我们用小波分析找出并剥离出代码中被修改最多的部分"——这个我才看得出我想继续读下去。
hxa7241查看英文原文
The other important thing needed is: Make your message concrete and specific. It is no use reading a first sentence that says something like: "We created a novel abstraction to improve software development.". Yes, it is concise, but it says nothing. "We used wavelet analysis to find and factor-out the most modified aspects of our code." -- that I can see I want to know more about.
外部约束（版面、成本）往往比自律更能逼出简洁。
我作为工程师得到的最好写作建议是："当然可以写九页，但期刊每超过六页就收 300 美元。"
dmlorenzetti查看英文原文
The best writing advice I ever had as an engineer was, "Sure it can be nine pages, but the journal charges $300 for every page over six."
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选