技术写作与文档2020news.ycombinator.com
Ask HN：请别再在Medium上写教程和技术文章
Ask HN: Please stop writing tutorials/tech articles on Medium
导读
这是一则 HN 上的公开呼吁：请不要再把教程和技术文章只发在 Medium 上，因为 Medium 的付费墙限制了读者的免费阅读，也与“从社区学到东西就该回馈社区”的精神相悖。评论区的讨论从读者的角度印证了这一点，也提出了平台选择上的权衡：Medium 提供 SEO 和排版便利，却牺牲了可及性，还容易让文章带上同质化的腔调。对写作者来说，这是一次关于“文章写给谁看、放在哪里”的清醒提醒。
可以直接用的写作要点
- 01
发布教程前先问一句“读者能否免费读到”：把知识放进付费墙，等于主动缩小了它的传播范围和学习机会。
- 02
平台带来的分发便利（SEO、排版、标准格式）是真的，但要权衡它牺牲的读者范围；想要长期积累，自建博客或静态站点往往更合适。
- 03
警惕被平台文风同质化：很多 Medium 文章有一种说不清的统一腔调，写作时要保留自己的声音，而不是套模板。
- 04
别为了“写一篇文章”而写：先确认自己有真实、具体、不过时的经验要分享，否则只会产出质量低下的内容。
- 05
如果确实想靠内容变现，让读者直接为作者付费，比让他们为偶尔一读的内容订阅整个平台更让人愿意接受。
HN 评论精选
付费墙把偶然路过的读者挡在门外；读者更愿意直接为作者付费，而不是为平台订阅。
过去三周里，Medium 几乎屏蔽了我想读的每一篇文章，要我付费。其中大多是讲 Rails 冷门特性的编程教程。说实话，我觉得 Medium 是最不适合放内容的地方。补充一句：我不反对别人靠内容赚钱，但那种情况下我更愿意直接付钱给作者本人（比如 GoRails），而不是为一个我偶尔才看一眼的东西订阅。
bnt查看英文原文
For the past ~3 weeks Medium has blocked virtually every article I wanted to read and is asking me to pay. Most of these are programming tutorials related to some obscure Rails features. Honestly, I feel like Medium is the worse place to put your content. EDIT: For context, I don’t mind people monetizing their content, but in that case I’d rather pay them directly (like GoRails), and not a “subscription” for something I might check once in a while.
缺乏真实经验的“为写而写”，是技术文章质量低下的根源。
我觉得大多数 Medium 技术文章写得差、内容过时，或者出自初级开发者之手。它们看起来像是那种“为了写文章而写文章”的人写的。
dplgk查看英文原文
I find most Medium tech articles to be written poorly or outdated or written by juniors. They seem to be written by people that want to write an article just to write and article.
Medium 用可及性换来了 SEO 和零门槛发布，这是它难以被替代的现实优势。
这里确实存在一个有趣的权衡。写作者想要读者，所以对一些人来说，牺牲“所有人都能看”来换取 Medium 的各种优势是值得的。面向技术写作的合理又免费的替代方案并不多：Medium 帮你搞定 SEO，让不会自己搭建托管的人也能极其简单地把想法公开出去；而且读者点开 Medium 链接时，也知道会看到标准化的排版。
Areibman查看英文原文
There's an interesting tradeoff here, to say the least. Writers want readers. So to some, it's worth sacrificing universal accessibility to gain all of the advantages Medium has to offer. There just aren't many reasonable, free alternatives for publishing written technical. Medium handles SEO and makes it super simple writers who don't know how to host their own content otherwise to get their ideas in public. Plus, readers who click on a Medium link know they'll see their content in a standardized format.
平台会塑造文风；技术写作者更适合自建博客，以保留个人声音。
我不认为 Medium 作为介于业余和专业写作之间的平台本身有什么问题，但它不适合大多数技术博客。对于只想传播想法和小技巧的人来说，用传统博客平台，或用静态站点生成器自己搭一个博客，几乎总是更好的选择。而且每个 Medium 作者似乎都会渐渐形成某种“风格”，我在别处看不到这种风格——我说不清具体是什么，但很多文章都有某种统一的腔调。
yabones查看英文原文
I don't think there's anything inherently wrong with Medium as a platform for the space between amateur and professional writing, but I don't think it's right for most techie blogs. For people simply looking to spread ideas and neat little hacks, it's almost always going to be better using either a 'traditional' blogging platform or homebrewing a blog with one of the static site generators. There also seems to be some sort of 'style' that every Medium writer starts to take on that you don't see other places, I can't put my finger on it but there's a certain tone to many of the articles.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选