技术写作与文档2014macdown.uranusjr.com
MacDown：macOS 开源 Markdown 编辑器
MacDown: Open-source Markdown editor for OS X
导读
这篇介绍 MacDown 这款开源 Markdown 编辑器，评论却把话题引向了一个更根本的问题：写作工具到底该为写作者提供什么。对写作者来说，值得读的是评论里关于「纯文本本身就该读得懂结构」「预览和性能如何打断写作节奏」的讨论。
可以直接用的写作要点
- 01
Markdown 的价值在于原始文本本身就大体能看出渲染后的样子，写作时应让标题、段落、列表在纯文本里就一目了然。
- 02
如果必须靠实时预览才能确认效果，说明结构表达不够清楚，这时更该回头改文字，而不是加预览窗口。
- 03
选写作工具的首要标准是不打断思路：卡顿、风扇狂转、按键延迟都会消耗写作状态。
- 04
不必被编辑器绑定，用自己熟悉的编辑器（哪怕是 vim）配一个自动刷新的预览工具，往往更省心。
HN 评论精选
纯文本应自带可读的结构，过度依赖预览反而削弱 Markdown 的优势。
对越来越多以实时预览为卖点的 Markdown 编辑器有点意外。我一直觉得 Markdown 最好的地方就是原始文本本身就大致能看出该怎么渲染；如果真的需要预览，那我几乎宁愿直接用所见即所得的编辑器。
rodion_89查看英文原文
Kinda surprised by the rise in markdown editors whose selling point is the live preview mode. I always felt that the best feature of markdown was that the raw text made it somewhat obvious how it should be rendered. If a preview mode is need I almost want to jump straight to a WYSIWYG editor
工具性能差会直接打断写作节奏，流畅度是写作工具的基本要求。
理念上我是喜欢的，但注意到它对我笔记本 CPU 风扇的实际影响：渲染 Markdown 的开销并不低——在示例文档的编辑区按一次键，就会触发 5 秒以上的满负荷 CPU 占用。打字打得风扇狂响，实在不是让人安心的体验。
kemayo查看英文原文
I'm conceptually a fan, but then I noticed its effect on my actual CPU fan. Whatever this is doing for rendering the Markdown is not cheap -- a single keystroke in the editor pane on the sample document triggers 5+ seconds of max-CPU usage. Typing causing loud fan noises from my laptop is not the most restful experience. https://www.dropbox.com/s/qy6szsbjs7cw3uv/Screenshot%202014-06-25%2020.17.17.png
把编辑器选择权留给用户、只做预览的工具，更贴合个人写作习惯。
我想我更喜欢 Marked。它允许我自己带编辑器（vim），只在检测到文件变化时自动更新预览。
stock_toaster查看英文原文
I think I prefer Marked. It lets me bring my own editor (vim), and simply aut-updates when it detects the file has changed.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选