技术写作与文档2020buttondown.email编辑精选
别用 Markdown 写文档
Don't write documentation in Markdown
导读
这篇讨论围绕“不要用 Markdown 写文档”展开，核心争议不是 Markdown 是否完美，而是文档到底该用什么工具才最容易让人真正写出来。对写作者而言，它提醒我们：降低写作摩擦、记录决策背后的“为什么”，往往比纠结格式更重要。
可以直接用的写作要点
- 01
优先选择自己和团队真正愿意用的写作工具，先降低启动阻力，把内容写出来。
- 02
文档不只解释代码“做了什么”，更要记录“为什么这样做”以及关键设计决策。
- 03
格式争论不应阻碍写作；不完美的文档也远胜于没有文档。
- 04
面向工程团队的文档要简单、通用、易更新，让维护成本足够低。
HN 评论精选
工具选择应看使用门槛和写作意愿，而不是理论上的最优。
这让我想起几年前一篇反 Markdown 文章下的评论：“在我看来，写文档最好的工具，就是任何人真的愿意去用的那个。Markdown 可能不完美，但至少简单、大家都懂，所以写和更新文档的门槛很低。”——warmans
husarcik查看英文原文
This reminds me of a comment on an anti-markdown post I read a few years back. "As far as I'm concerned the best tool for writing documentation is the one that anyone can actually be bothered to use. Markdown might not be perfect but at least it's simple and commonly understood so there isn't much barrier to writing/updating documentation." - warmans [1] https://www.reddit.com/r/programming/comments/4ck2lu/why_you_shouldnt_use_markdown_for_documentation/
文档的第一目标是有人写，Markdown 胜在低摩擦。
这没抓住重点。目标是“请把文档写出来”。对工程师来说，哪种方案阻力最小？目前绝大多数情况是 Markdown。它不完美，常常缺少技术写作者想要的特性，但能覆盖大多数用例，而且开发者愿意写。所以请用你喜欢的任何方式写文档，只要写出来。
1MoreThing查看英文原文
This is missing the point. The goal is "please write your documentation." What solution has the least friction around that for engineers? Right now, it's overwhelmingly Markdown. It's not perfect, and often doesn't provide the features a technical writer or other content specialist might want, but it handles most use cases and is something developers are willing to write in. So please, write your documentation in whatever you feel like. As long as it gets written.
代码不能替代文档，尤其要记录“为什么”和设计决策；有文档胜过格式完美。
与此同时程序员在想：请写文档吧！求求了。哪怕是用 Markdown 写的文档，也比经常出现的“什么都没有”强。很多程序员说代码就是最好的文档。并不是。源码回答了怎么做和是什么，却没有回答最重要的问题——为什么。软件体现许多架构和设计决策。哪些决策是明确做出的、为什么？看代码时我常常能理解做了什么，但并不能立刻看清为什么。在我合作的团队里，我让他们记录这些决策，帮助很大——有时过三年多再问，原实现者都不记得当初为什么那样做。要是我的问题是“大家用 Markdown 写文档”就好了；现在我只想要有文档。拜托？
taylodl查看英文原文
Meanwhile programmers are like: Please write documentation! Please. I'm begging you. Even documentation written in Markdown is better than the nothing that all-too-often gets created. A lot of programmers argue the code is the best documentation. No it's not. Source code answers the how and what but it doesn't provide any answer to the most important question of all - why? Software embodies several architectural and design decisions. What decisions were explicitly made and why were they made? All too often when looking at code I can certainly understand what was done, but it's not at all immediately clear as to why. On the teams I've been working with I've gotten them to capture these decisions. It's been a great help - sometimes the original implementors can't remember why something was done the way it was done - especially when asked three or more years later. Admonishing people to write documentation in Markdown would be a nice problem for me to have. Meanwhile I'd just like some documentation at all. Please?!
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选