技术写作与文档2022surfingcomplexity.blog编辑精选
把文档写好：软件工程师为什么该在意？
Writing docs well: why should a software engineer care?
导读
这篇博文讨论软件工程师为什么应当重视文档写作：写不好文档，工具就没人愿意用，工程师本人也会被“必须亲自解释”的重复劳动困住。三位评论者把话题从写文档扩展到通用的技术写作：补齐新手入门和完整参考手册之间的任务型示例，并分享可操作的排版、精简与修改技巧。任何需要向他人解释复杂事物的人，都能从中得到可以直接照做的写法。
可以直接用的写作要点
- 01
在入门教程和完整参考手册之间，补一组中等难度的任务型示例，回答“我要做 X 该怎么做”，并配一份术语和概念清单，别让读者在细节里迷路。
- 02
把读者不需要的内容坚决移走：删掉对理解主旨可有可无的部分，放进脚注、边注或链接文档，让正文更短。
- 03
找一个人读初稿；当读者提出疑问时，不要口头解释，直接把答案改进稿子。
- 04
用加粗和小标题把长段文字切开，尽量用列表，避免大段文字吓退读者；每段控制在三到五句，并注意朗读时的节奏。
HN 评论精选
文档决定工具是否被采用；最该补的是连接入门与参考的“任务型示例”和概念清单。
不管开源还是商业项目，文档写不好，别人就不会用你的东西；即便勉强用，也会一路抱怨。现在最缺的是任务驱动型文档：通常只有入门指南和参考手册，两者之间有一大段空白。入门项目往往只停留在 hello world 级别；参考手册列全了所有组件，却常常缺少概念和术语清单，你查某个东西时根本不知道它在你手头任务里处于什么位置。补上一系列中等难度的“我要怎么做……”示例，最能填上这段空白。还要列出各平台的特殊注意事项，别只说 Mac 用 homebrew、Ubuntu 用 apt-get。再开一个问答论坛，把最常见的问题收进 FAQ 或示例。永远别说“手册里有”，尤其当手册有一千页、每个功能只有两句话、没有任何用例的时候。
TheOtherHobbes查看英文原文
Whether it's FOSS or corporate, people won't use your stuff if it's not documented properly. At best they'll use it reluctantly and complain about it. One thing there isn't enough of is task-driven documentation. Typically there's a getting started guide and a reference manual, with a huge gap between the two. The getting started project is usually at the hello world level - ok as far it goes, which is not far. The ref manual typically has a list of all moving parts but often lacks a list of concepts and terminology. So you look up $thing and have no idea how it fits into what you're attempting to do. A series of mid-level task-based examples ("How do I...") for the most common use cases goes a long way to bridging that gap. Also list any platform specific quirks. (Not just "To install this use homebrew $name for MacOS and apt-get $name for Ubuntu.") And run a forum where people ask questions. Collect the most common questions into a literal FAQ and/or include them in examples/reference. Never say "That's in the manual." Especially not when the manual is 1000 pages long and gives a two sentence description of every feature with no use cases.
加粗引导视线、狠心删减、用改稿代替口头答疑、多用列表。
文末的建议很实用，我再补几条对我帮助极大的：每个小节用一两次加粗，打破单调，把读者的视线引到你想强调的地方；精简！删掉任何对理解主旨非必需的内容，移到脚注、边注或链接页面；找个人读你的初稿——如果他提问，不要直接回答他，去改稿子；把列表当作必须遵守的规则，大段文字最容易让人失去注意力。
verdagon查看英文原文
The tips at the end of the article are pretty solid. I'll add some more that helped my writing immensely: * Use bold text once or twice per section to break up the monotony and draw the reader's eye to where you want it. * Shorten! Cut away anything optional to the reader understanding your main point, and move it to footnotes, sidenotes, or a linked document/page. * Have someone read your first draft. If they ask a question, don't answer it directly! Update your draft instead. * Use lists religiously! Walls of text tend to repel attention. My favorite article [0] happened to use all these tips, if anyone wants to see an example. Happy writing! [0] https://verdagon.dev/blog/higher-raii-7drl
清晰的技术写作是工程师放大自身影响力的关键技能。
对工程师来说，几乎没有什么技能比简洁清晰的技术写作更重要，它让工程师的影响力超出个人时间的限制。
socialismisok查看英文原文
There are few skills more important to an engineer than concise, clear technical writing. It enables engineers to scale beyond themselves.
写作是有意识的计划与清晰度训练；人们抗拒写作，往往是因为书面记录带来责任。
段落偏长时写三句，句子较短、语言节奏又在时可以到五句。在真正练习过清晰表达、遣词和专注写作（不靠拼写检查、不靠辅助工具）之前，说明任何复杂事物都像在做计划：要用多少篇幅才能讲清楚？换成一张图会不会更好？要不要加个图表辅助？我靠把领域专家（航空、建筑、工程、SaaS、华尔街）的话“翻译”成商务语言写投标文件，过得还不错。十次有九次，对方能顺畅地跟我口头讲一遍，可书面稿却拖过截止日期三天还没动笔，这给我添了不少麻烦。显然，人们在商业环境里讨厌写作。为什么？因为一旦写下来就留下记录、要担责任，这吓坏了那些想含糊其辞使用语言的人——所以发完邮件还要打电话说一遍，就是不用回复按钮。太可预测了。
WallabyEV查看英文原文
3 sentences per paragraph if long-ish, can go 5 if shorter and the rhythm is present in the cadence of language. Basically until you practice clarity, word choice, and active attention to writing (no spell check, no assists), communicating anything of complexity becomes a planning exercise. How much will it take to convey this information in text? Would a picture work better? A graph to support? I've made a nice living "translating" from Subject Matter Expert (A/C/E, SaaS, Wall St) into business language for RFPs. 9 times out of 10 a person can talk out a story to me just fine - meanwhile they've stalled writing anything for 3 days past the deadline so it's just making my life more difficult. It's obvious people hate writing in the business realm. Why? Because once it's written down there's a paper trail and accountability. That scares people who want to use language in shady ways. Hence the phone call after your email to talk about what you just mentioned but not by using the Reply button. Sooooooo predictable....
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选