技术写作与文档2010sheddingbikes.com
如何编写一本《Learn X the Hard Way》
How To Write a Learn X the Hard Way
导读
这篇文章讲如何写“Learn X the Hard Way”式教程：把学习过程拆成一步步可执行练习，边做边写，先记录所有步骤，再清空环境重走以补漏。对写作者的价值在于：它提供可操作的方法避免专家盲点、把大任务拆成小块，也提醒你要根据读者水平选择教程还是参考书。
可以直接用的写作要点
- 01
写教程时逐步记录每个操作，别因为自己熟练就跳过“显然”的细节。
- 02
初稿完成后清空环境或换新读者视角按步骤重走，补上遗漏的步骤。
- 03
把“写一本书”拆成可管理的小练习或章节，避免笼统庞大的待办事项。
- 04
先明确读者：新手教程重动手少讲解；有基础者可能更需要完整参考和细节索引。
HN 评论精选
写教程要逐步记录并清空环境复走，补上专家盲点；对项目文档同样适用。
诀窍是你必须一步步记录自己输入的每个操作。程序员常把安装这些东西当作第二天性，于是会跳过非程序员根本不知道的细节和重要步骤。写好说明后，清空机器或虚拟机，再手动重走一遍，你会碰到漏掉的东西并补上。这个方法不只适用于写书，也很适合写项目文档，比如“三小时内搭好开发环境”；我常用 Google Doc 共享，近来用 Fabric 把步骤写成可读的自文档化脚本，一条命令即可运行。
sghael查看英文原文
"The trick is you have to document everything you type step by step. The problem programmers have is they know how to install this stuff like it's second nature, so they skip details and important steps that non-programmers just don't know. Once you have your instructions, erase the machine (or VM) and go through the steps again, manually. You'll run into stuff you missed and will need to fill those missing steps in." This applies to a lot more than writing a book and is great advice to anyone who is writing documentation for their code/project. I find this technique particularly helpful when writing a "How to get our development env up and running in 3 hours or less" document. Most of the time I just write it down in a Google doc and share with my team. But lately I've been documenting all steps with Fabric, which has the dual benefit of being very readable ("self-documenting") code as well as a one-command setup script 'fab -h <target>'. And the way I create my Fabric scripts is basically what Zed describes above.
动手敲代码并运行比单纯阅读更有效，适合设计初学者教程。
昨晚我和 10 岁儿子做了前两个练习，他很喜欢。我意识到 LPTHW 的方法正是我小时候学编程的方式：进计算机实验室，拿到印着 BASIC 程序清单的练习纸，敲进 Apple II 并运行，在过程中学习。读得少，做得多。
cschmidt查看英文原文
I did the first two exercises last night with my 10 year old son. He really liked it. I realized that the LPTHW method is exactly the same way I learned to program as a kid. We went into the computer lab and they gave us worksheets with BASIC program listings on them. We typed them into the Apple II's and got them running, learning in the process. It was much less reading and more doing.
把大写作任务拆成可管理的小块，避免 monolithic 待办。
这看起来是写书或其他大型作品的很好方法。它避免把待办事项写成“写书”这种庞然大物，而把工作拆成可管理的块。
stuartk查看英文原文
This looks like a really nice way to write a book, or in fact any other large body of work. It avoids the monolithic todo list item - 'write book', and breaks things up into manageable chunks.
教程式写法不适合有基础读者；参考书需完整细节、不手把手。
说明写得不错，但我个人讨厌这样写的编程书。如果你成年后从没编过程，第一门语言可能需要这种书；但已会编程的人会觉得这种格式冗长浪费。我想要语言参考，覆盖语言所有组件，再按字母列出常用类库，这就够了。关键是每个东西都要有细节：如果我要用多维数组，书里必须有相应代码，否则没用。别在学习上牵我的手，但要把使用语言所需信息都放进桌上一本两英寸厚的书。很少书做到；我只想到一本：O'Reilly 的 DHTML Definitive Guide。照那个格式做就是好编程书；偏离到“21天自学”或“Cookbook”就失去我。
jasonkester查看英文原文
Nice instructions, but I personally hate programming books that are written this way. I suppose if you've made it to adulthood having never programmed a computer, you might need a book like this for your first language, but if you already know how to program, this format is just tedious and wasteful. Give me a language reference that covers all the components of the language, followed by an alphabetical listing of the most common class libraries that you'll need to use. And that's it. The trick though is that you need detail for everything. If I'm firing up a multi-dimensional array, your book had better have the code to do that, or it's worthless. Don't hold my hand on the learning side, but have all the information I need to use the language in one 2-inch thick chunk of paper on my desk. Very few books get this right. I can think of exactly one, in fact: O'reilly's DHTML Definitive Guide. Copy that format exactly, and you'll produce a good programming book. Deviate into "teach yourself in 21 days" or "Cookbook" land, and you've lost me.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选