技术写作与文档2022markdoc.io
Markdoc：Stripe 基于 Markdown 的内容创作框架
Markdoc: Stripe's Markdown-based authoring framework
导读
Stripe 开源了支撑其官方文档站的 Markdown 写作框架 Markdoc，评论区围绕“工具如何影响文档质量”展开讨论，并把它与 MDX、MkDocs 等方案做比较。值得写作者一读的原因在于：好文档既靠长期的人力打磨，也靠让人愿意反复更新的顺手的工具。
可以直接用的写作要点
- 01
文档质量的差距主要来自持续投入的编辑时间，工具的价值在于降低“想不想动手改”这一阻力。
- 02
挑选写作与发布工具时，优先选自己用起来顺手、愿意天天打开的那个，产出自然更稳定。
- 03
在 Markdown 中嵌入组件，可以让正文、示例和图表同步维护，减少内容过期。
- 04
选型时多横向比较同类工具的实际写作体验，例如搜索、标签、分栏等，而不只看功能清单。
HN 评论精选
工具是否顺手，直接决定团队愿不愿意持续维护文档。
Stripe 的文档长期是业界标杆，主因当然是他们投入的细心与人力；但和任何创作一样，工具也很重要——如果团队不喜欢自己维护文档所用的内容管理系统，他们就更不可能去更新它。作为花了几百小时读他们文档的用户，我很感谢这个团队，也佩服他们把 Markdoc 开源。
cdevroe查看英文原文
Stripe's Docs have been best-in-class for a long time. Obviously, the care and human hours they put into their upkeep is the main reason for the Docs being so good. But, as with any creative endeavor, the tools matter. If the Stripe team didn't like the content management system they used to keep the Docs up-to-date they'd be less likely to do it. As someone that has used their Docs for hours and hours and hours I'm thankful to their team for how good their Docs are. Very cool of them to open source this. Looks great.
质疑新框架的独特性，提醒先弄清它与既有方案（如 MDX）的差异。
我不太明白它和 MDX 有什么本质区别，MDX 早就能在 Markdown 里混用 React 组件了。我们就是用它搭 Streamlit 文档的，我以为大家都是这么写文档的。
etchalon查看英文原文
I don't understand how this is fundamentally different than MDX, which can already mix React components within Markdown. We used it to build the Streamlit docs. I assumed this is how everyone was doing documentation: https://github.com/streamlit/docs
横向试用多个方案后再定，实际写作体验（如搜索、标签）是关键。
给正在找文档生成工具的人：我最近评估了 VuePress、Docusaurus 和 AsciiDoc，最后选了 MkDocs Material。从标签、分栏到非常好用的内置搜索，都挺惊艳，值得一看。
_miau_hoch2查看英文原文
For anyone looking for a doc generation tool: I was lately evaluating several tools like VuePress, Docusaurus and AsciiDoc. I ended up using Mkdocs Material (https://squidfunk.github.io/mkdocs-material/). If you haven't already, have a look. I think it is pretty impressive. From tags, tabs to the fantastic built-in search ...
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选