技术写作与文档2013conf.writethedocs.org
面向所有技术文档写作者的会议
A conference for all those who Write the Docs
导读
这篇帖子介绍 Write the Docs 会议，评论围绕技术文档展开：开源项目常被批评文档差，口头愿意写的人多但实际贡献少；有人提出“文档驱动开发”，也有人强调文档质量是组织是否真重视写作的试金石。对写作者来说，它提醒我们文档需要前置设计、明确贡献机制和真实反馈，而不只是事后修补。
可以直接用的写作要点
- 01
当别人说你的文档差时，别只做零散修补；要指定真正在意的人集中负责，并把“愿意写”变成明确任务和可提交的稿件或 PR。
- 02
可以借鉴“文档驱动开发”的思路，把文档前置到设计阶段，而不是写完代码再补。
- 03
警惕“恐怖谷文档”：看起来完整规范，实际用户却用不起来；要建立机制收集真实使用中的卡点并持续改进。
- 04
判断一个组织是否真重视写作，不看口号，而看是否投入资源并建立反馈和改进机制；个人写作同理，不能只靠零散热情。
HN 评论精选
开源项目文档常被批评，但口头愿意写的人多、实际提交少；维护者需要想办法吸引技术写作者并让贡献真正发生。
我是一个小型但还算活跃项目的维护者，最常听到的批评是“文档很烂”，而且确实如此。有人口头愿意写文档，却没人提交过 PR；我零散修补不够，需要真正在意的人集中投入。很多技术写作者有 GitHub 账号，怎样才能吸引他们来参与项目？
tych0查看英文原文
I'm the maintainer of a small but reasonably active project, and the most frequent criticism I hear of the project is that our documentation sucks. And it's true! Several people have offered to write documentation, but I've never received any pull requests. I fix up the documentation here and there, but it'll never get where it needs to be without a focused effort by someone who really cares. (And it's not that I don't, I just have a long code TODO list as well...) A lot of these technical writers have github accounts, where presumably they contribute to open source projects in the form of documentation. Does anyone have any tips for attracting such people to a project?
文档质量暴露组织是否真正重视；比明显缺失更糟的是“看似合格、实际难用”的文档，因此必须建立发现改进点的机制。
文档写作是一个组织是否言行一致的试金石。文档不仅有时被直接忽视，还常被带进“恐怖谷”：看起来像合格的文档，但实际程序员用起来仍然很糟。如果组织真的重视文档，不仅会投入资源去写，还会认真建立机制来找出哪里需要改进。想想看，这甚至可以成为判断该投资哪些大型软件公司的指标，尤其是如果你能高效识别“恐怖谷”文档。（不仅是股票，也包括使用他们的 SDK/API。）对小软件公司来说，一开始可能没有足够的人手写文档。
stcredzero查看英文原文
Doc writing is a canary for how well an organization puts its money where its mouth is. Not only is documentation sometimes outright neglected, it's most often taken into an "uncanny valley" of plausibly looking like decent doc, but still sucking when actual programmers use it. If an organization is really serious about documentation, they will not only devote resources to writing it, they will also devote serious attention to a mechanism for figuring out where it needs improvement. Come to think of it, this would be a decent metric for figuring out which big software companies to invest in, especially if you can detect the "uncanny valley" docs efficiently. (Not only equity, but in use of their SDK/APIs.) For small software companies, there may not be enough people to write docs at first.
提出“文档驱动开发”这一主题，把文档放到开发流程的前端。
我刚提交了第一个演讲提案，叫“文档驱动开发”。简短介绍在这里：(http://blog.factor.io/post/41716938796/docs-driven-development)
mskierkowski查看英文原文
I just submitted the first talk proposal called "Docs-driven development". Here is a brief intro: (http://blog.factor.io/post/41716938796/docs-driven-development)
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选