技术写作与文档2020reasonablypolymorphic.com编辑精选
如何写出让人愿意读的技术文章（2019）
How to write technical posts so people will read them (2019)
导读
这是 2019 年一篇关于“如何写技术文章才有人读”的经验帖，作者从版式、标题、可扫读性等具体技巧入手，讨论怎样让读者愿意读下去。评论区把话题推向更深层：技术写作最难的其实是判断读者是谁、假设他们已知多少，以及舍得删掉不重要的内容，因此对写作者很有参考价值。
可以直接用的写作要点
- 01
动笔前先明确读者是谁、他们已经懂多少，宁可偏向“假设读者不懂”，把背景铺垫补足。
- 02
先以意识流方式一口气写完，隔一两天再回看，你自然会看出哪些地方过于技术化、需要补一座从读者已知到本文的桥。
- 03
用标题、加粗、要点等视觉线索让习惯快速扫读的读者迅速找到重点，别让他们读了三段还问“重点是什么”。
- 04
写作的重心是删减：把“什么都记下来”的平铺直叙改成有观点、有取舍的表达，细节可以推到附录或脚注。
HN 评论精选
技术写作真正要平衡的是对读者已知信息的假设，宁可写得更好懂，并用“先写完再补引入”的方法搭桥。
这篇文章谈的是排版和表面文风。技术写作真正的难点更深一层：你的读者是谁？你假设他们已经知道多少？人容易走极端，要么把世上一切重讲一遍，要么假设读者什么都懂，这个平衡出乎意料地难。我的结论是宁可偏向“可理解”这一边，哪怕是学术论文这类高度技术性的写作也如此。一个有效的做法是：先意识流地写完，它必定过于技术化；隔一两天回来一看就明显了；然后补一个更通俗的开头，在读者的起点和文章之间搭一座桥，再据此改写正文；细节必要时推到补充材料、附录或脚注里。
unclesaamm查看英文原文
This article talks about formatting and other superficial stylistic issues. The main challenge of writing a technical post is deeper: who is your audience? And how much do you assume they already know? The temptations are to take extremes: either you have to reexplain everything in the universe, or you assume you're talking to someone who already knows everything. I've found this surprisingly hard to balance. In the end, though, I decided it's always better to err on the side of comprehensibility. This is true even for highly technical writing like scholarly articles. One way that I've found works is to first write it out, stream of consciousness. Invariably this will be too technical. That will be obvious after waiting a day or two and revisiting it. Then build a bridge between where you are now and where the article is, with a more general introduction, and revise the body to flow with that new introduction. It's okay to push details to a supplement or appendix or footnote if necessary.
读者是用“跳过”的方式阅读的，文章必须用标题、加粗等视觉线索尽快交出重点，否则读者会去评论区找总结。
值得每个在 Hacker News 发帖、参与讨论的人快速读一遍。文中引用的这句话很关键：花大量时间阅读的人很擅长跳过文本，理解这些跳过规律就能让人轻松找到想找的东西，而且别忘了他们是在找“继续读下去的理由”，他们要的是你想告诉他们的，而不是你实际写出来的。我无数次点开首页高赞文章，读三四段还在问“重点是什么”，因为文章没有标题、加粗、提示框之类能吸引人读下去的东西。这时我就跳到评论区看有没有人总结要点，通常真有人总结，有时还能把我拉回去继续读；另一些时候，看得出有人没理解“读者在找继续读下去的理由”这句话。
gwbas1c查看英文原文
Good skim for anyone who's posting to Hacker News and participating in Hacker News discussions. > People who spend lots of time reading have good heuristics for skipping lots of text. If you understand these heuristics, you can make it easy for people to find what they’re looking for. And remember: they’re looking for reasons to continue reading. ... They’re looking for what you’re trying to tell them, as opposed to what you’re actually saying. I can't count how often I've come across a highly-ranked HN article and asked myself "what's the point" after 3-4 paragraphs. Then, the article has no headings, bold, callouts, ect, that would entice more reading. At this point I flip over to the Hacker News discussion to see if anyone's summarized the point. Usually someone does, (and sometimes it entices me to continue reading.) Other times, it looks like someone just doesn't understand "And remember: they’re looking for reasons to continue reading"
好写作的核心是艰难地取舍删减，把“什么都写”的扁平文档变成有重点、有观点的表达。
文章漏掉的一个概念是：好文章需要在“删掉什么、不谈什么”上费大力气思考。初学写作的技术作者常把一切都照抄记录下来，结果重点“扁平”，什么都同等重要，这是懒于思考。团队站会上照念脑子里所有东西、占用大家时间的人就是如此，通常说明他没有提前准备、想清楚要说什么。要压缩成“哪些东西对别人重要”“哪些细节该提、哪些不该提”，需要真正下功夫：每写进一个词就挤掉了另一个词，哪些词最重要？把扁平的文档变成对别人有用的视角，需要功夫、对使用场景的理解和思考，往往意味着有观点的编辑和写作。
supernova87a查看英文原文
I think one concept missing from the post is that good writing takes heavy thought on what to remove and not talk about. Beginning developers or writers of technical information often just transcribe and document everything. In that, the emphasis of the writing is "flat". Everything is equally important. That is lazy thinking. You encounter this in people doing standup summaries for their teams and just regurgitating everything on their minds, taking up people's time. Usually it means they haven't prepared in advance and thought through what they're going to say. It takes actual work to distill that to "what things matter to other people?". "What details are important to mention, and not to mention?" Every word included takes away from another word that could be said. Which words are most important? It takes actual work, understanding of the use cases, and thought, to turn flat documentation into perspective that people find useful. It means often, opinionated editing and writing from a point of view of, what's important (if it is not a pure reference work).
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选