技术写作与文档2022css-tricks.com编辑精选
面向开发者的技术写作
Technical Writing for Developers
导读
这篇文章面向开发者讲技术写作，而 HN 上的讨论把重点从语法纠正拉回到“为读者写作”。一位有十年经验的写作者指出，语法恐惧是开发者不敢动笔的主要原因，真正的核心是了解读者和他们的需求；评论里还推荐了优秀的写作范例和一本系统教材。适合想写文档、教程或技术博客的写作者读。
可以直接用的写作要点
- 01
别被语法吓住：技术写作的关键是写得有用、能帮到人，而不是句句完美。
- 02
动笔前先弄清读者是谁，去读他们的 Stack Overflow 提问、看文档站点的使用数据、发问卷，并让他们容易给反馈。
- 03
按读者的需求组织文档，可参考 diataxis 的四类划分（教程、操作指南、参考、解释）。
- 04
像 React 教程那样循序渐进：先铺垫基础概念，再引入状态管理等复杂内容；同时保持写作建议自洽，别让模板和要求互相矛盾。
HN 评论精选
语法不是门槛，技术写作的核心是了解读者、按需写作。
有十年经验的技术写作者。文章一上来就谈语法，这在我看来是警示信号，甚至是危险信号：很多开发者正是因为怕语法出错才害怕技术写作。别担心这个！记住技术写作的核心原则：1）了解你的读者，和他们交流，看他们的 Stack Overflow 提问，分析文档网站的使用数据，做问卷，让他们容易给反馈；2）针对读者的需求写作，diataxis.fr 是个好起点，它归纳的四类需求覆盖了开发者 90% 的常见需求。写文档是帮助他人极其有效的方式，别追求完美，专注于有用、有服务意识。
kaycebasques查看英文原文
Technical writer with 10 years of experience. The way this post starts off talking about grammar is a yellow flag for me, if not red. Many developers/engineers get scared of technical writing precisely because of their fear of not using grammar correctly. Don't worry about that!! Just remember the cardinal rules of technical writing: 1. Know your audience. Talk to them. Look at their Stack Overflow questions. Analyze your documentation website usage. Run surveys. Make it easy for them to provide feedback. 2. Write for that audience's needs. https://diataxis.fr is a great start because those 4 needs cover 90% of the most common developer needs. Documentation is a profoundly effective way to help people. Don't worry about doing it perfectly. Just stay focused on being helpful and of service.
写作和流程上的建议要自洽，与原则冲突的模板只是冗余。
PR 相关的建议有点奇怪，和几条“把 PR 做小”的建议相矛盾：如果提倡小 PR，就不该让模板把功能改动、新功能和 bug 修复混在一起问；本地 lint 和测试的勾选要么不可信，要么在 CI 环境下可以自动化，没必要制造摩擦。另外，“程序员不擅沟通”这个刻板印象真该消失了。
BlargMcLarg查看英文原文
The pull request advice is strange in conjunction with several suggestions which boil down to "make PRs smaller". > What types of changes does your code introduce to Appium? Surely that would be obvious from the connected issue. If you suggest smaller PRs, it doesn't make a whole lot of sense to potentially combine feature changes, new features and bug fixes. Which makes that part of the template redundant beyond the exceptions. > - [ ] Lint and unit tests pass locally with my changes In the context of non-CI environments, I wouldn't trust anyone who signed this to begin with. In the context of CI environments, you can make this both uniform and automated. Why risk friction where there doesn't need to be any? >Now, the programmer stereotype is that we’re poor communicators Slight tangent: this stereotype seriously needs to die. I've been hearing this since studying CS, and I still see both clients and client-facing employees make basic mistakes they try to hammer out of students in year 1-2, while continuing to use this stereotype against programmers. It's become an excuse for client-facing and coordinating types to push ICs to adapt to them instead of the other way around.
好的教程会循序渐进地铺垫概念，再引入复杂内容。
有没有优秀技术写作的例子？Stripe 常被称赞，但我觉得 React 的教程也很棒：他们很擅长先慢慢铺垫技术概念，再抛出管理状态这类更大的概念。
lelandfe查看英文原文
Anyone got some favorite examples of great technical writing? Stripe gets a lot of love, but I think React's tutorials are also wonderful: https://reactjs.org/docs/hello-world.html They did a stellar job of slowly building technical concepts before hitting you with bigger concepts like managing state.
推荐系统学习技术写作的专著《Docs for Developers》。
值得提一下去年出版的一本好书：docsfordevelopers.com。
tusslewake查看英文原文
Worth mentioning this great book on the subject published last year: https://docsfordevelopers.com/
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选