技术写作与文档2011leanpub.com
Tell HN：我正在写一本 Erlang 食谱书，你有兴趣吗？
Tell HN: I'm writing an Erlang recipes book, are you interested?
导读
这是一位作者在 Hacker News 上征集读者对一本 Erlang 菜谱书（cookbook）的兴趣，评论区讨论的其实是"技术书该怎么写"。对写作者来说值得一读：它提醒你，菜谱式写作的重点不在堆砌技巧，而在于用例子传递架构思路和设计原则。
可以直接用的写作要点
- 01
菜谱书不要只罗列零散的小技巧，应围绕连贯的主题或设计原则来组织内容。
- 02
写读者真正卡住的地方（如架构、监督树），而不是他们已经能查到的语言基础。
- 03
可以按"任务导向"和"语言导向"两条线编排内容，兼顾查工具和学方法两种需求。
- 04
动笔前先测试读者兴趣和付费意愿，能帮你判断这个选题值不值得写。
HN 评论精选
读者要的是架构层面的实战案例，尤其是如何用好 OTP behaviors 和监督树，而不是语言基础技巧。
光讲 Erlang 语言本身的菜谱，我没多大兴趣；但如果写成 Erlang/OTP 菜谱、重点放在 OTP 上，那我百分百支持。我真正想看的是真实 Erlang/OTP 软件的架构案例。我近年主要写 Python，但做过几个 Erlang 副业项目，最难的一直是怎么把 OTP behaviors 用到位、搭出一棵能正常工作的监督树。我勉强能跑通，但总觉得不够 OTP，也判断不了自己做得对不对。
Xixi查看英文原文
Erlang recipes, not that much. Make that Erlang/OTP recipes with a strong emphasis on the OTP side of it, and a million times yes ! Or to say it slightly differently : I'm not that much interested in recipes about the Erlang language itself, but I'm very very interested in recipes/examples of architectures of actual Erlang/OTP softwares. I'm doing mostly Python these days, but I worked on a couple of side projects in Erlang in the past (a large one ~3 years ago, and a small one ~6 months ago). And for me the hardest was (and still is) to figure out how to use the OTP behaviors in an optimal way. How to make a nice, working supervision tree. I managed to pull working stuff out of the ground, but somehow it never fell OTPish. I couldn't tell if I did it right or wrong.
菜谱应承载设计原则和思维方式，而非零散技巧的拼盘。
不知道这是否和菜谱书的定位相冲突，但请考虑借这些菜谱讲连贯的主题或设计原则，而不是简单给一堆有用的小零碎。Erlang 有很独特的基础（函数式编程加上事件驱动的强大能力），相关书籍又少，这是个大好机会：教 Erlang 的思维方式，而不只是技巧合集。
elliot42查看英文原文
I don't know if this is antithetical to these recipe/cookbooks, but please consider teaching coherent themes or design principles via these recipes, rather than simply providing an assortment of useful tidbits. Erlang has such a unique foundation (functional programming + event-driven awesomeness) and so few books that there is a great opportunity to teach the Erlang mindset/perspective and not just a bunch of tips and tricks.
菜谱书应把任务导向和语言导向结合起来，并给出具体的任务清单。
感兴趣！我特别喜欢那种既任务导向又语言导向的菜谱书。比如 Doug Hellman 的 PyMOTW 就是讲解 Python 标准库的绝佳指南，这类内容会是书的重要部分。不过书里也该有一些任务导向的内容，比如：用标准 inets 服务器以及 webmachine、nitrogen、yaws 等第三方库托管静态文件的 Web 服务器；如何记录日志；如何启用追踪，等等。
asymptotic查看英文原文
Yes, I'm interested! I'm particularly interested in recipe books that are both task-oriented and language-oriented. For exaple, Doug Hellman's PyMOTW is a phenomenal guide to using libaries that are part of the Python standard distribution and would be a key part of the library. However, some aspects of the recipe book should be task oriented: - Web server hosting static files using the standard inets server, and 3rd party libraries like webmachine, nitrogen, and yaws. - How to log - How to enable tracing etc.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选