技术写作与文档2021signalsandthreads.com编辑精选
技术地写作
Writing, technically
导读
这篇围绕技术写作展开，讨论技术写作者如何推动机构知识共享，把邮件等渠道里的有用知识整理成可检索、可持续维护的文档。评论还指出，公司若真重视协作与知识共享，就应投入专职技术写作者，而不是让开发者在赶项目时顺便写文档。对写作者来说，它提醒我们：写作不只是产出文字，也是设计知识如何被保存和传播。
可以直接用的写作要点
- 01
把埋在邮件线程里的知识整理成公开可检索的文档，是让机构知识可扩展、可持续的具体做法。
- 02
主动将一次性沟通转化为永久文档，是技术写作者推动知识共享的关键动作。
- 03
如果组织只口头强调知识共享却不投入专职写作者，文档工作往往会落到不擅长也不喜欢写作的开发者身上。
- 04
技术写作也包含倡导更好的知识存储方式，而不只是把现有内容写清楚。
HN 评论精选
技术写作者应把邮件等临时沟通中的机构知识转成可检索文档。
开头提到一件我在技术写作生涯早期就深有体会的事：作为技术写作者，我常倡导用更可扩展、可持续、永久的方式存储机构知识。典型例子是邮件——有时极其有用的知识埋在邮件线程里，我常和工程师等人合作，把这些知识变成可公开搜索的文档。
kaycebasques查看英文原文
The intro touches on something I learned to be true very early in my technical writing career, but which isn't discussed much and may not be widely known: > helping to push forward all sorts of efforts around knowledge-sharing at Jane Street As a TW I often find myself advocating for more scalable/sustainable/permanent ways to store institutional knowledge. The classic example is email. Sometimes there is extremely useful knowledge buried in an email thread. I often work with engineers (or whoever) to turn that knowledge into publicly searchable documentation. P.S. tangentially related to the title of this post, my brother came up with a fun self-deprecating joke (which I later used on as a tagline [1]) > Technically, I'm a writer [1] https://developer.chrome.com/blog/welcome/
组织应投入专职技术写作者，别把文档负担推给开发者。
我认为很多公司如果雇几名技术写作者会受益匪浅。管理层总在谈协作和知识共享，却不愿为此掏钱。结果只能由员工在赶项目截止日期的同时写文档，而大多数开发者并不真的喜欢写，也不擅长写。
spaetzleesser查看英文原文
I think a lot of companies would benefit immensely if they hired a few tech writers. Management always talks about collaboration and knowledge sharing but they refuse to put money behind this desire. Instead it’s up to the workers to create documentation while also having to finish project deadlines. And most developers don’t really enjoy writing or are good at it.
Google g3doc 团队有类似文档经验，可延伸参考。
我听了一部分，觉得很棒。其中许多经验与 Google g3doc 团队的收获相似。
gravypod查看英文原文
I listened to some of this today and it's really great. Lots of similar learnings as has been had from the g3doc team at Google. More information available here: https://www.youtube.com/watch?v=EnB8GtPuauw
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选