技术写作与文档2020developers.google.com编辑精选
技术写作课程
Technical Writing Courses
导读
这是 Google 官方免费技术写作课程（两门），讲受众定义、主动语态、短句、文档结构等基础方法。评论区既有对课程组织方式的肯定，也有资深从业者对"技术文档通病"的批评，值得写作者对照自省：好文档不等于把所有细节讲全，而是帮读者完成他想做的事。
可以直接用的写作要点
- 01
动笔前先明确读者是谁、他们已经知道什么、读完后要做什么，这决定了你该写什么、跳过什么。
- 02
优先用主动语态和短句：句子越短、主语越明确，读者理解成本越低，技术内容尤其如此。
- 03
别只给"列出资源"这类玩具示例，要给读者真实场景：拿到数据后怎么处理、怎么用。
- 04
少铺垫、先给全貌：开头讲清整体图景，再进入细节，避免读者在枝节里迷路。
HN 评论精选
课程结构清晰、原则易记，值得先看再评价。
读完这里的评论，我怀疑不少人根本没点开链接看内容。这两门课结构其实很好：每门课有总纲列出所有课时，每课又有目录概览要点，用几条易记的原则把技术写作的核心主题讲透。我上大学时要是课程也这么有条理就好了。亮点包括：定义你的受众、吸引受众（主动语态）、以及短句如何提升理解度。
mattlutze查看英文原文
After reading some of the comments here, I'm wondering if people are actually following the link and reviewing the content. The two courses are well-structured. Each course has an overall outline listing each lesson, and each lesson has a table of contents to overview the topics therein. The courses highlight major key topics in technical writing and does so with easy-to-internalize (tenets). I'd have loved for my university coursework to be so clearly organized. Some highlights include defining your audience[1], engaging your audience[2] and reviewing how short and clear sentences improve comprehension[3]. 1: https://developers.google.com/tech-writing/one/audience#define_your_audience 2: https://developers.google.com/tech-writing/one/active-voice 3: https://developers.google.com/tech-writing/one/short-sentences
文档要服务读者的真实目标，先给大局再讲细节。
这就是"没人看文档"的原因。这类课程是典型的技术写作者式过度设计：只见树木不见森林，然后又陷进杂草里（请允许我混用比喻）。开头铺垫和设置太多，接着直接跳到细枝末节，始终没给出全局图景。如果这是 Google 的技术写作者写的，那水平之平庸让我意外。写文档只需要两样东西：对主题的理解，以及对读者想做什么的高层把握。读者不是想用你的 API 列出资源，他是想给自己的用户一份可继续操作的资源清单。所以你不该给"获取供应商列表"这种无意义示例，而该示范如何取出列表、处理其中有用的字段并展示出来。当然，如果 API 或 UI 本身就逻辑一致，那会省事很多。
205guy查看英文原文
This is why “nobody reads documentation.” These courses are typical tech-writer overkill, missing the forest for the trees, then getting lost in the weeds (if I may mix a few metaphors). There is too much introduction and setup, then it jumps into the nitty-gritty, but never gives the big picture. Assuming this was written by the Google tech writers, I’m surprised at how middle-of-the-road the offering is. I kinda assumed they had an academic-like cutting-edge writing department. To write documentation, you need 2 things: an understanding of the subject matter, and a high-level understanding of what the readers want to do. The reader doesn’t want to use your API to list resources, the reader wants to give his/her users a list of resources for further operations. So you don’t give a trivial example of getting the list of providers, you give an example of how to display providers by getting the list and processing the various useful fields. It also helps if the API or UI or whatever is logical and consistent to begin with.
推荐《经济学人》与美国陆军风格指南作为范例。
我见过最好的风格指南是《经济学人》的（附链接），美国陆军写给领导层的写作风格指南也相当不错。这里（课程中）的例子非常好。
sandGorgon查看英文原文
The best i have seen is the economist style guide - http://cdn.static-economist.com/sites/default/files/pdfs/style_guide_12.pdf the US Army writing style guide for leadership is also pretty good - https://www.esd.whs.mil/Portals/54/Documents/DD/iss_process/Writing_Style_Guide.pdf The examples here are very very good.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选写出更好的错误信息
Write better error messages
这篇帖子讨论如何写出更好的错误信息，评论补充了开发者场景下的具体做法和真实反面案例。
技术写作与文档2022 · 566 分 · 253 评4 条写作要点编辑精选写一本技术书的经济账
The Economics of Writing a Technical Book
一位技术书作者拆解写书的真实经济账：版税收入往往远低于投入的时间成本。
技术写作与文档2018 · 519 分 · 149 评4 条写作要点编辑精选Diátaxis——技术文档编写的系统化方法
Diátaxis – A systematic approach to technical documentation authoring
Diátaxis 是一套把技术文档按「教程、操作指南、参考、解释」四类拆分的写作框架，核心是让每一篇文档只服务一种读者需求、只承担一种写作任务。
技术写作与文档2024 · 514 分 · 113 评4 条写作要点编辑精选