技术写作与文档2020capiche.com
Markdown 背后的故事
The Story Behind Markdown
导读
这篇文章追溯 Markdown 的起源与演变，但评论区读者对它提出了尖锐批评：它把一些技术细节（如 CommonMark）突然抛出，却没有解释清楚；又漏掉了 Pandoc 等真正重要的工具。对写作者来说，这组讨论本身就是一堂关于「结构、取舍与读者预期」的写作课。
可以直接用的写作要点
- 01
动笔前先想清楚要讲的故事主线，可以画提纲或结构图，标出每个事实在什么位置、以什么方式引入。
- 02
不要在读者毫无准备时突然抛出陌生概念（如 CommonMark）；要么先把背景交代清楚，要么干脆删掉。
- 03
先做足功课，识别题材中最重要的「高峰」，别花了大量笔墨写边角细节，却对核心工具（如 Pandoc）视而不见。
- 04
技术类文章的叙述顺序要服务于理解：让每个术语和例子都能和前文接上，否则读者读到一半就会放弃。
HN 评论精选
写作要先有清晰的故事结构和充分调研，别让读者被突然出现的陌生概念卡住，也别漏掉题材中最重要的对象。
作者您好：这个题材我很感兴趣，所以兴致勃勃地开始读，但读到一半就沮丧地停了。请把以下当作善意的建议：先想清楚你要讲的故事，可以列提纲或画图，标出在哪里引入哪些事实。比如文中突然提到一个叫 CommonMark 的东西，链接到看起来只有技术人士才关心的规范文档——它是什么？和上下文有什么关系？另外要做足研究，知道这片领域里最高的山峰在哪。为什么只描写山脚，却对眼前显眼的山顶视而不见？关于漫画的那几段很精彩，但 Pandoc 在哪？我不是要求你写我会写的那篇文章，但 Pandoc 正是 Markdown 的应用：它把 Markdown 变成编写 HTML、TeX、PDF、Office 格式等的工具，体量巨大。总之，我喜欢你们网站的样子（但同意其他人说的，不该劫持浏览器快捷键）。
leephillips查看英文原文
Advice to the author: This is a subject I am interested in, so I began your article eagerly, but had to stop about halfway through out of frustration. Please consider these as the constructive suggestions that I intend them to be: Think about the story you want to tell. Maybe make an outline or diagram, marking at which points you will introduce which facts. Example: For some reason something called Commonmark is abruptly mentioned, with a link to spec documents that would seem to be of only technical interest. What is this, and how is it connected to anything else? Do enough research so that you know the highest peaks in the landscape. Why describe the foothills and take no notice of the prominent mountaintop right in front of us? Example: the bits about the comics were fascinating. But where is Pandoc? I don’t think I’m guilty, here, of demanding that you write the article I would have written. But Pandoc is the application of Markdown. It turns Markdown into a way to author HTML, TeX, PDF, Office formats, and a lot more. It‘s huge. Anyway, I like the look of your site (but agree with others that you should not hijack browser shortcuts).
CommonMark 通过处理边缘情况统一了 Markdown 的解释，这一贡献值得在叙述中给足分量。
文章似乎轻描淡写地带过了 CommonMark 的巨大贡献：它主要通过考察那些没人会想到、直到在实际使用中才出现的边缘情况，保证了 Markdown 解释的一致性和通用性。
jchook查看英文原文
The article seems to gloss over the enormous contribution CommonMark made to ensuring a consistent and versatile interpretation of markdown, mostly by examining edge cases no one thinks about until they appear in the wild.
文章涉及的人物背后有更大的故事，值得展开，但这条评论更偏情感缅怀而非写作方法。
这只是 Aaron Schwartz 参与过的众多了不起的事情之一。这么年轻就失去他，真令人惋惜。我确实相信，如果他还活着，今天的互联网会有所不同。
jgilias查看英文原文
Just one of the great things Aaron Schwartz was involved in. So sad we lost him so young. I really do believe the Internet would somehow be a different place now if he was still around.
从读者体验出发：标准不统一会带来真实的使用摩擦，写作与工具设计都要考虑这种一致性。
难道只有我一人觉得烦吗——每个网站都想实现自己那套特殊且互不兼容的 Markdown 子集？说的就是你，Hacker News，你让引用块都很难写。
jandrese查看英文原文
Am I the only person that gets annoyed that every single site wants to implement their own special and incompatible subset of markdown? Yes, I'm looking at you HackerNews, who makes it hard to block quote.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选