技术写作与文档2018nanxiao.me
通过写一篇教程来学习新技术
Learn new technology through writing a tutorial about it
导读
这篇文章主张通过写教程来学习新技术：把学到的东西讲清楚，是检验和深化理解的有效方式。值得写作者读，是因为它把“教”与“写”放在一起讨论；而评论区则进一步争论：写教程该不该发布、对读者负有什么责任、初学者视角与专家视角各自的价值在哪里。
可以直接用的写作要点
- 01
把写作当作理解的检验：能用自己的话把一个概念讲到初学者听懂，才算真正掌握。
- 02
面向初学者写作时，优先用“比你早几步的人”的语言，而不是专家的术语和默认前提。
- 03
发布前先问自己：我有没有新内容或新讲法？没有就把教程当私人笔记，不必强行公开。
- 04
动笔前确认自己确实懂，避免把半懂的知识包装成权威教程误导后来者。
HN 评论精选
不懂就别写教程，低质量教程会误导新人。
我们就是这样搞出了成千上万个垃圾质量的安卓开发教程。我曾想查怎么保存应用专属数据，谷歌和 DDG 排名前十的教程全是让人新建一个叫“myapp”的目录来存数据。几年后谷歌不得不和 Udemy 合作做系列教程，才真正教人用不愚蠢的方式做事。请不要写你并不懂的东西的教程。新人会访问你的博客，以为你是专家，然后照着做。
akerro查看英文原文
That's how we ended up with 1000s of garbage quality tutorials for android development. I was once looking how to save app specific data and all top 10 tutorials in google and DDG were saving data to userspace by creating new directory called something like 'myapp'. Years later Google had to create a series of tutorials with Udemy (as I recall) to actually tell people how to do things in a not stupid way. Please don't write tutorials about things you do NOT know. Newcomers will visit your blog and think you're an expert and do it this way.
教是最好的学；初学者视角有独特价值，读者需保持批判性思维。
是的，请写你的教程。学习某样东西最好的方式，远胜其他，就是去教。对那些说“我们不想再多一篇烂教程，只想听专家”的人，我完全不同意。第一，判断某样东西是否合理，是学习者自己的责任；你不能也不该盲目相信网上的东西，连专家也会出错，学习时要不断问“为什么”。第二，专家离初学者的心态太远，往往缺乏用简单语言解释的能力；比你领先几步的人，更有可能用你的语言来解释。我们需要传播更多知识，而不是更少。初学者学习新技术的经验是有价值的知识，即使有些细节可能不对。只要读者保持批判性思维，我们都是赢家。
amorphous查看英文原文
Yes, please write your tutorial. The best way to learn something, by far, is to teach. To those who say "but we don't want another crappy tutorial we only want to hear from experts" I heartily disagree. First, it is your responsibility as a learner to decide if something makes sense or not. You can not and should never just believe something on the internet. Even experts get things wrong. Keep asking "why" while learning. Second, experts are far detached from the beginner's mindset and often lack the ability to explain something in simple terms. Someone who is a few steps ahead of you will have a better chance to explain things in your language. We need to spread more knowledge, not less. A beginner's experience with learning a new technology is valuable knowledge, even if some details may not be correct. As long as the reader keeps his critical thinking hat on, we all win.
入门教程泛滥、高级内容稀缺；为自利而写的教程价值有限，发布前要想清动机。
在我看来，“[技术]入门：第一部分”这类教程太多了，高级主题的课程却远远不够。就“为了自己学习而写教程”而言，这已被证明有效，作为个人收益这是很好的建议。但为了初学者和教程社区的创作者，请考虑写完后把这些教程丢掉。它也许某天能帮到人，但你得考虑最初动机：个人提升。出于对教学的热爱、为提升周围人知识而教的课程往往最好，因为出发点是无私的；为创作者自身提升而做的课程往往没那么有帮助。
k1ns查看英文原文
In my opinion, we have far too many "Getting Started With [technology]: Part 1" tutorials and not nearly enough lessons on advanced topics. I get it, creating these lessons takes time and dedication that often isn't apparent until you're nearly done. I've started work on combating this phenomenon myself by creating lessons that do cover advanced topics but even those fall short of where I'd like them to be. When it comes to "writing a tutorial" for the benefit of your own knowledge, it's been proven to work. This is very good advice when it comes to personal gain. However, for the sake of beginners and content creators that are active in the tutorial community, please consider throwing out these lessons when you're done. It might help someone out there at some point but you have to take into account your initial motive: personal advancement. Lessons that are taught out of passion for teaching and advancing the knowledge of those around you are often the best because they come from a selfless place. Lessons created for the creator's own advancement are often not as helpful. This is something I struggled with when creating my own tutorials. Was I creating it out of love for teaching others, or was there some hidden motive that even I might not be aware of? This is simply my own opinion, take my comment with a grain of salt. I'd be interested to hear what others think about the prevalence of "beginner" tutorials juxtaposed with an apparent lack of those that would be considered "advanced".
教学可以自用，但发布要有新意——新内容或新讲法。
你想写多少教程都行——教学是验证和精炼自己理解的好方法——但请不要觉得非发布不可！正如其他人所说，这就是我们最终有成千上万低质量教程和糟糕 StackOverflow 答案的原因。只有当你有什么新东西要说，或有新的表达方式时才发布。我发表的（极少数）文章大多属于第二类，反响非常好。
ggambetta查看英文原文
Write all the tutorials you want -- teaching is a good way to verify and refine your own understanding -- but please don't feel compelled to publish them! As other posters have said, this is how we end with thousands of low quality tutorials and bad StackOverflow answers. Publish if you have something new to say, or a new way to say something. The (very very few) articles I've published fall mostly into the second category, and have been extremely well received.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选