技术写作与文档2018blog.stoplight.io编辑精选
当你不是技术写作者时，该如何写文档（第二部分）
Writing Documentation When You Aren't a Technical Writer – Part Two
导读
本文面向并非专业技术写作者的人，讲如何写出可用的文档；HN 讨论把重点进一步归结为“了解读者与目的”，并提醒可以借鉴高质量文档的结构。对写作者来说，它值得读，因为这些原则同样适用于说明文、教程和产品文案。
可以直接用的写作要点
- 01
动笔前先明确读者是谁、他们读完后要完成什么任务，再决定详略与结构。
- 02
把高质量文档当作参照，但按自己的产品、场景和资源做裁剪，而不是整段照搬。
- 03
把“了解读者和目的”当成通用检查项，写完后逐段问：这段话帮读者解决什么问题？
- 04
看似常识的写作规范也值得列成清单，因为常识在实际写作中并不常见。
HN 评论精选
写文档的首要能力是了解读者及其目的，这能普遍提升沟通效果。
我写 Chrome DevTools 和 Lighthouse 的文档。在本系列第一篇的讨论中我提到，写出有用文档最关键的能力是了解你的读者。combatentropy 进一步指出还要了解目的：写得好需要知道读者和目的，之后路径会清晰很多；写作规则能写满整本书，但大多数写作只要记住读者和目的就能大幅改善。做了 8 年专业技术写作后，我强烈建议把重点放在了解读者及其目的，这是一项能改进任何沟通的超级技能。
kaycebasques查看英文原文
I write the docs for Chrome DevTools and Lighthouse. In the discussion for part 1 of this series I mentioned that the #1 most critical skill for creating useful docs is to know your audience. combatentropy expanded on the idea [1] to include purpose: > I have been a tech writer, and I would say something similar, that you need to know two things to write well: audience and purpose. The road becomes a lot clearer after that. Rules on writing fill whole books, but most writing would improve tenfold if writers remembered audience and purpose. These articles are fine, they have good tips. But, after 8 years of professional technical writing, I strongly recommend focusing on knowing your audience and their purpose. This is a superskill that you can apply to improve any communication. [1] https://news.ycombinator.com/item?id=17839052
可以比较并改造高质量文档来提升自己的文档，但要考虑资源与来源差异。
最近我读到一个鲜明对比：ReasonML 和 MDN。我知道这不公平，因为 MDN 投入的资源和时间多得多，ReasonML 文档又基本照搬 OCaml 文档；但可以比较 Reason 的 List.map 和 MDN 的 Array.map。既然 Reason 文档是从 OCaml 文档改来的，我想知道把 MDN 文档拿来、改出 Reason 所需的相关子集会有多好。
icc97查看英文原文
I've been reading a stark comparison recently, ReasonML vs MDN. I realise this is unfair as MDN has had much more resources and time and the ReasonML docs are a straight copy of the OCaml docs, but compare the Reason List.map [0] vs MDN Array.map [1]. Given that the Reason docs are taken from OCaml and modified , I was wondering how well it would work to take the MDN docs and modify the relevant subset for Reason. [0]: https://reasonml.github.io/api/List.html#VALmap [1]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map
把常识写成指南仍有价值，因为常识并不总是被实践。
这是一组不错的指南。大多是“常识”，但考虑到常识往往并不常见，它对目标读者可能相当有帮助。
chrisweekly查看英文原文
Nice set of guidelines. Mostly "common sense" but given how (un)common that can be, this is likely pretty helpful for its intended audience. :)
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选