技术写作与文档2023editor.vrite.io
开源协作式所见即所得 Markdown 编辑器
Show HN: I've built open-source, collaborative, WYSIWYG Markdown editor
导读
这是一个开源的、支持协作的所见即所得 Markdown 编辑器发布帖，作者介绍了功能、技术栈与不足。评论区最有价值的部分是对“Markdown 要不要所见即所得”的争论：有人提醒 Markdown 的初衷是让纯文本本身就好读。对写作者来说，这提醒我们重新思考格式与文字的关系。
可以直接用的写作要点
- 01
写 Markdown 时尽量让未渲染的纯文本也能顺畅阅读，格式只是辅助，句子本身要站得住。
- 02
不要依赖“看不见的格式”承载意义；如果删掉标记后读者会误解你的意思，就说明表达还不够清楚。
- 03
在纯文本与所见即所得之间按场景取舍：快速成稿可用富文本界面，需要精确控制结构与可移植性时回到源码模式。
- 04
工具的选择应以减少写作摩擦为准，不要为了炫技或排版细节反复折腾编辑器。
HN 评论精选
Markdown 的价值在于纯文本本身就好读，所见即所得反而偏离了它的初衷。
恭喜你把东西做出来并发布上线了！不过 Markdown 原始文档里说得很清楚：其格式语法的首要设计目标是尽可能易读，一份 Markdown 文档应该能直接当作纯文本发布，而不像被标签或格式指令标注过。以我的经验，Markdown 的好处恰恰是省掉了所见即所得的必要，因为所见即所得用起来很痛苦。把这两点放在一起，看到 Markdown 被这样使用我觉得挺奇怪——不是说它错或不好，只是觉得奇怪，似乎违背了它的初衷。
Brendinooo查看英文原文
Congrats on building and shipping something! That said, from the original document about Markdown[0]: > The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. From my experience, the benefit of Markdown is that it eliminates the need for WYSIWYG, because WYSIWYG is awful to work with. Put those two things together, and it's weird for me to see Markdown used like this. Not saying it's wrong or bad or whatever, just that it's weird and seems to cut against the spirit of the thing. [0]: https://daringfireball.net/projects/markdown/
编辑时应能看见全部 Markdown 标记，而不是让格式符号变成不可见字符。
如果能有一个模式，让你看到完整的 Markdown 语法，同时又保留 Markdown 所表示的格式效果，那就太好了。我个人觉得把不可见字符增删掉很奇怪。
Palmik查看英文原文
It would be great if there was a mode that allows you to see the full markdown syntax (while still applying formatting implied by the markdown). I personally find it strange to remove / add invisible characters.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选