技术写作与文档2019news.ycombinator.com
Ask HN：为什么教程作者要把 10 项技术凑在一起，而 1 到 2 项就够了？
Ask HN: Why do tutorial writers combine 10 technologies when 1 or 2 would do?
导读
这篇 HN 讨论源于一个常见困惑：为什么一个只讲 GraphQL 的教程，非要捆绑 Express、React 等一堆技术？几位评论者从教学设计、创作者动机和读者生态三个角度拆解了原因。对写作者来说，它提醒我们：教程不是知识展示，而是为读者设计一条能走通的学习路径。
可以直接用的写作要点
- 01
先明确学习目标：读者学完这篇应当能做什么、理解什么，再据此删掉无关技术。
- 02
用最小可运行示例教学，避免用一堆框架掩盖核心概念。
- 03
警惕“专家诅咒”：你对读者已知内容的假设，往往正是他们卡住的地方。
- 04
把教程当作服务读者，而不是展示自己技能或堆砌代码量的广告。
HN 评论精选
教程作者常缺乏教学设计意识，也很少获得真实读者反馈，容易陷入“专家诅咒”。
多数教程作者并不懂如何设计教学材料。他们不深究学习目标（读者最后应当会做什么、理解什么），不懂得如何给出简洁可运行的示例、如何“搭脚手架”式地循序渐进。教程常常只是把自己学过的东西、以及自己怎么学的倒出来，但这不意味着对别人也有效。做教学材料很难，而很少有人在真正从学生/读者那里获得反馈；如果你从没观察过新手如何使用（以及在何处挣扎于）你的材料，你就不知道哪里缺失、含混或让人不堪重负。我做了很久培训课程，仍然不确定自己是否对学生的已知做了太多假设——这就是“专家诅咒”——也不确定他们会卡在哪里。
tedyoung查看英文原文
Most tutorial writers are not aware of how to create educational materials. They don't think deeply about the learning objectives (what the reader should be able to do or understand at the end), don't understand how to provide concise working examples, how to "scaffold" learning, and so on. It's often just a dump of the things they learned and maybe how they learned it, but that doesn't mean it'll work for anyone else. Creating teaching materials (tutorials, documentation, etc.) is hard, and few tutorial writers are getting feedback from actual students/readers. If you're never watched how novices work (and struggle!) with the materials that you've created, you don't really know what's missing or confusing or overwhelming. Even though I've been creating training courses for a long time, I still never know whether I'm making too many assumptions about what the student knows -- this is the "curse of expertise" -- and where they'll get stuck or lost. (btw, I talk about some of the theory of learning with examples in my "Human Learning" presentation that you can find on YouTube: https://www.youtube.com/playlist?list=PLBHctPrH7Z2-BcpRWJ0uFanCbTHqdJ_1T)
教程常是作者自我营销的产物，堆技术是为了秀技能、显代码量，而非服务学习。
人们做教程有经济动机，这些动机并不总和帮你学习完全一致。做教程能提升个人曝光度，带来别处更赚钱的机会（因为做教程本身的收入不如实际就业或接咨询）。而且如果教程是作为自己能力的广告，你就想做得越快越好，并展示雇主欣赏的技能。最快的方式往往是做你本来就想做的东西，或改造你已为客户/项目做过的内容；最简单的办法则是拿官方文档示例改一改，于是就有了新教程，还顺便提升了个人形象——大家都赢，只有读者赢得没教程作者多。为了向雇主展示能力，你还得考虑哪些技能让你“值钱”：所以哪怕 GraphQL 教程前端用不了多少，你也可能塞进 React/Redux，因为（1）你擅长 React/Redux，得秀一下；（2）代码越多，在很多人眼里越厉害。
bryanrasmussen查看英文原文
People make tutorials for economic reasons, those reasons are not always 100% aligned with the need to help you learn. Making the tutorial increases their profile, leading to more profitable opportunities elsewhere (because making the tutorial is not as financially remunerative as actually being employed/consulting somewhere). Furthermore if you make a tutorial as an advertisement for your skills you want to make it as quickly as possible and show off skills that an employer will appreciate. Probably the quickest way to do something, or to decrease the cost of doing it is to work on something you want to make anyway or to adapt something you already made for a client/project. OF course the easiest way is for people to just go ahead and take the official documentation examples and tweak them a bit and now we have a new tutorial showing you how it is done and we have also managed to improve our profile! Everybody wins, only you don't win as much as the tutorial writer. Because you want to show off skills to the employer you might also have to consider what the skills you think make you bankable - especially if you have a plan as to where you're going. So even though your GraphQl tutorial might not need much on the frontend you may want to throw React/Redux in there because 1. you're good at React/Redux so gotta show that off 2. more code looks more impressive to a lot of people. Finally, When you make a tutorial on GraphQl you will need to have some sort of backend, frontend etc. so you have to choose something, probably you decide to put those together based on what your skills are, based on what you have that you've worked on that can be adapted to tutorial purposes, and a number of other factors. At any rate there is not much economic incentive for most people who make tutorials to make the best tutorial for educational purposes that they can make, unless it is their plan to be educators in the future.
很多教程捆绑技术栈，是因为读者本就带着生态内的具体问题来学，而非想孤立地掌握某项技术。
以 GraphQL 为例，很大一部分想学它的人，是想在 React 和 Express 环境里用它，因为他们有一个前端问题要解决。那些博客其实并不是在讲 GraphQL 本身的全貌，而是在讲如何在作者（以及大量读者）熟悉的上下文——Node.js、Express、React 应用——中使用它。这类文章数量巨大，正是把开发者拉进 React、Express 生态的因素之一：在既有大生态里解决具体问题的文章，远多于纯粹讨论某个热门但尚未普及的新技术的文章，因为大生态里的潜在读者多得多，而他们想读的正是如何在自身体系里解决问题。早年微软开发者部门把这称为三种开发者人设的差异：最高的是“爱因斯坦”，想搞懂技术的一切；最低的是“Mort”，一个只想学点脚本打印业务报表的牙医；中间是“埃尔维斯”，想学到能理解自己在做什么、能完成工作即可，不追求全懂。
yodon查看英文原文
A huge fraction of the people who are trying to learn to use GraphQL (to use your example) are trying to learn to use it in the context of React and Express because they have a front end problem they need to solve with it. The blogs they write aren't really about understanding GraphQL in totality or on its own, they are tutorials on using GraphQL in a context with which they the authors (and a great many of the readers) are familiar, namely Node.js apps running Express and React. The huge number of posts like you refer to is one of the things that draws developers into an ecosystem like React and Express. There is simply far more written about how to use shiny-new-thing in the context of solving a problem in a big existing ecosystem than in the context of pure discussion of some hot new but still largely unused tech, largely because there are so many more potential readers in that large existing ecosystem, and those readers want to read how to solve the problems they face in their ecosystem. Long ago Microsoft's Developer Division talked about this as the difference between three different developer personas. The fanciest persona was "Einstein" who wanted to understand everything about how the tech worked. The lowest was "Mort" who was a dentist who just wanted to learn to write a little bit of script to print a report he needed for his business. And in the middle was "Elvis" who wanted to learn enough to understand what he was doing and to do his work but was ok not understanding everything. Most front end devs are not in the "Einstein" category of how they learn technologies. They are much more motivated by the need to solve an immediate business problem, and they tend to do a lot of blogging because there are so many of them.
不少教程作者自身理解不深，能力有限才转去写教程（观点偏激，但点出了质量参差的现象）。
多数教程作者在自己所教的东西上其实很糟糕。他们可能对某个概念有模糊的把握，但也就到此为止。如果能力更强，他们就不会去写教程了。当然有例外，但这至少涵盖了在 Udemy 这类网站做课程的人中的 90%。这又回到那句老话：“能者做，不能者教。”
fright查看英文原文
Most tutorial writers are terrible at what they are trying to teach. They may have a vague grasp of a concept, but that's about as far as it goes. If they were more capable they wouldn't be writing tutorials. There are of course exceptions to this, but it covers at least 90% of the people who create courses for sites like Udemy. Comes back to the old saying, "Those who can, do. Those who can't, teach."
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选