技术写作与文档2016gitbook.com
Show HN：GitBook 编辑器 Beta——Markdown 所见即所得，支持 TeX
Show HN: GitBook Editor Beta – Markdown WYSIWYG, TeX
导读
GitBook 发布编辑器 Beta，主打 Markdown 所见即所得与 TeX 公式渲染。HN 上的讨论很快从功能转向一个更实际的问题：写长篇「正经文档」到底该用什么工具？话题涉及在 LaTeX 之上叠加所见即所得、把 Markdown 当作 pandoc 的原生交换格式，以及是否该把稿件托付给订阅制编辑器。对写作者来说，这是一次关于「写作与排版分离」的实用讨论。
可以直接用的写作要点
- 01
为长篇作品选定一种纯文本源格式（如 Markdown），让写作与排版、发布格式解耦，随时可换工具而不丢稿。
- 02
公式或复杂排版交给实时预览去承担，别在源码和成品之间来回切换，把注意力留给内容本身。
- 03
把稿件保存在自己可控的本地纯文本文件里，谨慎让第三方服务进入「交给编辑或付印之前」的写作流程。
- 04
工具选择上优先考虑能对接多种输出格式（如 pandoc）的方案，避免被单一平台锁定。
HN 评论精选
所见即所得层可以架在 LaTeX 之上，让公式密集的文档也能边写边看到成品。
你也可以看看 Overleaf：它在完整的 LaTeX 发行版之上提供了一层富文本（所见即所得）编辑，并在浏览器里把编译后的文档自动预览显示在源码旁边。它主要面向研究论文和相关材料，但什么都能写——最早的项目之一（不是创始人做的）就是一套婚礼请柬。（PS：我是创始人之一，欢迎反馈。）
JohnHammersley查看英文原文
You might also want to check out Overleaf[1] -- it offers a rich text (WYSIWYG) layer on top of a full LaTeX distribution, with an automatic preview of the compiled document alongside the source in the browser. It's geared primarily towards research papers and associated material, but can be used for anything! One of the first projects (not by the founders) was a set of wedding invitations! [1] https://www.overleaf.com PS: In case you can't guess, I'm one of the founders, and any feedback is always appreciated, thanks.
面向正式文档而非网页笔记的 Markdown 编辑器长期缺位，插件化编辑器只能临时补足。
编辑器不错。我一直觉得面向「真正文档」的 Markdown 编辑器还有很大空间——之前一直用 Atom，配上合适的插件能覆盖很多场景，我甚至写过一个做类似行内数学渲染的插件。
mangecoeur查看英文原文
Neat editor, I've long felt there's room for a markdown editor geared to writing 'real' documents - been working with Atom which covers a lot of ground with the right plugin - I even wrote a plugin that does something similar to their inline math rendering: https://atom.io/packages/preview-inline
长篇写作应把稿件保存在纯文本源格式里、围绕 pandoc 自由转换，而不是把流程锁进订阅服务。
我最近在写一本新书，一直在定写作流程。我边写边把章节当博客文章发，但在 WordPress 里编辑体验很差，我也不认为 HTML 适合做书的权威源文件。我第一本书和很多旧文档用 SGML DocBook 写，后来转成 XML DocBook：好处很多，配合顺手的 vim 配置并不难用，输出格式也非常灵活，最终出版用的是出版社模板的 Word 文档。不过那都是很久以前了，现在文档可以从很多格式起步、落到很多格式，pandoc 完全改变了规则，而 Markdown 似乎是最「原生」的 pandoc 格式。总之我觉得我该用 Markdown 写作。但这个工具完全不适合我：为文本编辑器付订阅费很别扭，在交给编辑或付印之前我不想让第三方介入流程；而且已有那么多优秀、灵活、强大、免费开源的编辑器，为这样一个功能有限的编辑器付费很奇怪。我想我只需要找一套好的 vim Markdown 配置，或者再给 Atom 一次机会。
SwellJoe查看英文原文
I'm working on a new book lately, and I've been trying to settle on the right workflow. I've been posting the chapters as blog entries, as I complete them, but editing in WordPress leaves a lot to be desired, and I don't really think HTML is the right authoritative source for a book. I wrote my first book, and a lot of old documentation in SGML DocBook, and then later converted it to XML DocBook...it had many benefits, and with a decent vim setup wasn't too hard to work with, and the output options were super flexible. Final format for publication was a Word doc with extensive templates provided by the publisher. All of that was a long time ago, though, and there's a lot more flexibility in where a document can start and end up in various other formats. pandoc changes the rules entirely, and markdown seems the most "native" format for pandoc. In short, I think I need to be working in Markdown. But, this doesn't look like the right tool for me, at all. A subscription service for a text editor just feels wonky. I don't really want anyone else in the workflow until I send it off to an editor or for print publication. And, the idea of paying for a text editor, especially one as limited as this one seems to be (though it has some neat tricks), when there are such good/flexible/powerful/free/open editors, seems bizarre. I think I just need to find a good set of vim settings for markdown, or give Atom another try.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选