技术写作与文档2010sheddingbikes.com
Zed Shaw 正在写一本教初学者 Python 的书
Zed Shaw is Writing A Book Teaching Beginner Python
导读
Zed Shaw 宣布要写一本教初学者 Python 的书，起因是他公开批评现有教材很烂。对写作者来说，这篇帖子的价值在于它呈现了一种教学写作的姿态：如何为初学者降低门槛、如何把批评变成具体作品，以及写作的“声音”可以怎样在他人帮助下打磨。
可以直接用的写作要点
- 01
写给初学者时，先别急着推荐高级工具或术语，把入门门槛压到最低；评论里那位偷偷换用简单编辑器、反而上手更快的初学者就是例子。
- 02
与其只吐槽别人的作品很烂，不如动手写一个替代品；批评只有落到具体的写作行动上才有分量。
- 03
教学文本可以坦诚划定边界：不承诺教会你一切，只承诺给你继续学习所需的基础。
- 04
写作的“声音”不是一次定型的，愿意让读者和同行参与打磨，作品才可能变得更有价值。
HN 评论精选
批评之后付诸行动，比单纯抱怨更有说服力。
Shaw 先生，你又一次让我佩服。这不是我第一次看到 Zed Shaw 吐槽他讨厌的东西，然后转身就去尝试把它修好。
pavelludiq查看英文原文
Mr. Shaw, i am once again impressed. This is not the first time I've seen Zed Shaw rant about something he dislikes and then goes off and attempts to fix it.
对初学者来说，简单工具比高级工具更友好，教学写作也应先降低门槛。
书里说：“如果程序员让你用 vim 或 emacs，告诉他别。这些编辑器是给更厉害的程序员用的。你现在只需要一个能把文字放进文件的编辑器。”哈！我刚开始编程时，所有人告诉我的都相反。挠头几周、花在学编辑器上的时间比写代码还多之后，我偷偷换成了 Pico。但天哪，Pico 我可用得太溜了。
fretlessjazz查看英文原文
"If a programmer tells you to use vim or emacs tell them no. These editors are for when you are a better programmer. All you need right now is an editor that lets you put text into a file." Ha! When I started to program, everyone told me the opposite. After weeks of head scratching and spending more time learning editors than coding, I secretly switched to Pico. But man could I use the hell out of Pico.
写作的“声音”可以在他人反馈中打磨，作品值得持续迭代。
我建议读一读他贴出的雏形 PDF，有些地方很好，有些地方没那么好；但如果 Zed 坚持下去、并愿意让别人帮助塑造他的声音，这可能会成为一个很有价值的项目。
callahad查看英文原文
I suggest reading the nascent PDF that he's posted, it's very good in some ways, less good in others, but if Zed keeps it up and is willing to have others help shape his voice, then this could end up as a very valuable project.
教学写作要明确边界：打基础而非包教一切；批评要用作品来跟进。
书里说：“你可能不会真的从这本书里学到‘编程’，但你会学到开始学习这门语言所需的基础技能。”这很好。这类书有它的位置。至少，他是在用具体行动跟进他那句“DiveIntoPython 是垃圾”。
ivenkys查看英文原文
From the book: "You might not really learn “programming” from this book, but you will learn the foundation skills you need to start learning the language. " This is good. There is a place for books like these. If nothing else, he is at least following-up his "DiveIntoPython is crap" words with concrete action.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选