技术写作与文档2012pencil.asleepysamurai.com
Show HN：一款免打扰的 Markdown 编辑器
Show HN: a distraction-free Markdown editor
导读
这是一则 Show HN 发布帖：作者用周末时间做了一个无干扰的 Markdown 编辑器，并开源了代码。对写作者来说，它值得一读的地方不在于工具本身，而在于它体现了「让界面退场、让文字留在前台」的写作工具思路；此外，评论区还顺带讨论了标题措辞如何影响读者预期。
可以直接用的写作要点
- 01
用纯文本 Markdown 写作，把排版交给渲染器，写作时只面对文字本身。
- 02
任何打断心流的反馈（例如保存提示）都应改成不打断输入的状态显示；工具设计如此，写作流程也如此。
- 03
标题里写明「side project、周末做的」这类限定，能管理读者预期，避免被误读成正式服务。
- 04
先发布一个最小可用版本，再根据真实反馈逐条修，而不是憋到完美才发。
HN 评论精选
标题里的限定词会塑造读者预期，删掉「side project」就可能被误认成商业服务。
版主能不能把 SideProject 这个词加回标题？我不想让人以为这是个托管服务之类的东西。顺带问一句，标题到底为什么被改了？我原本提交的标题是「Show HN: Sideproject - I built a distraction free Markdown editor last weekend」。说真的，这里的版务管理有点过于强势了。
chaosprophet查看英文原文
Mods, please put back the word SideProject into the title. I don't want people thinking this is a hosted service or something like that. On a related note, why was the post title modified at all? For reference, the original title I submitted was 'Show HN: Sideproject - I built a distraction free Markdown editor last weekend'. Seriously, the moderating is getting quite heavy handed here.
打断写作的反馈提示应改为不打断操作的状态显示，不要弹出窗口。
反复点击或切换焦点时，「已保存！」弹窗有点烦人，我觉得直接显示在屏幕某个角落就行。不过我很喜欢这个编辑器，恭喜！如果想做得更进阶，能在预览模式里直接编辑会很棒——我觉得可以用 contenteditable 实现，退出预览时再把改动合并回 Markdown。
josscrowcroft查看英文原文
The "Saved!" dialog gets a little pesky when repeatedly clicking around or focusing/unfocusing. I think it could just be displayed somewhere on the screen. But I love the editor - congrats! If you feel like going more advanced, it'd be amazing to be able to edit while in preview mode - this could be done with contenteditable I think, and the changes merged back into markdown when exiting preview mode...
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选