技术写作与文档2014medium.com编辑精选
亲历技术写作的未来
Living the Future of Technical Writing
导读
这是 Scott Chacon 关于技术写作工作流的文章，核心是把写作当成软件工程来做：用纯文本/Markdown 写作，用 Git 管理版本，用工具链自动生成 HTML、PDF 等多种输出。评论区分享了各自的实践，也讨论了网页与纸质两种输出在排版质量上的取舍。对写作者来说，这篇值得一读，因为它把“内容与格式分离”“保存即预览”这些工程思路直接搬到了写作流程里。
可以直接用的写作要点
- 01
用纯文本或 Markdown 写正文，让内容和排版格式分开，这样同一份稿子可以生成网页、PDF 等多种版本，也方便用 Git 做版本管理。
- 02
把写作流程工程化：保存文件就自动重新构建预览，缩短反馈循环，比写完一大段再整体检查更容易保持状态。
- 03
先想清楚最终载体是网页还是纸质/PDF，再选工具链：评论里反复提到，同一套工具很难在两种输出上都做到高质量。
- 04
排版质量值得投入精力：读者能感觉到成品的精致程度，所以像 softcover 这类专注排版质量的构建工具才会有人专门去做。
HN 评论精选
Markdown→LaTeX→PDF 加自动重建预览，是兼顾写作效率与排版质量的实用工作流。
他分享了自己写 Haskell 教材的工作流（github.com/bitemyapp/doc-workshop）：用 Pandoc 把 Markdown 编译成 LaTeX，再由 LaTeX 渲染成 PDF；每次保存 Markdown 文件时，PDF 预览会自动重新渲染。Pandoc 允许在 Markdown 里直接内嵌 LaTeX，自动重建脚本由 mwotton 提供。他用 Emacs 编辑，但编辑器可以随便选。
coolsunglasses查看英文原文
Humbly submitting the way I work on my book for learning Haskell: https://github.com/bitemyapp/doc-workshop Uses Pandoc, compiles markdown to LaTeX, LaTeX renders to PDF. Dynamically re-renders the preview of the PDF as I save my markdown files. Pandoc admits inline LaTeX in the markdown documents themselves. Auto-rebuilder script by http://twitter.com/mwotton Learn about Pandoc here: http://johnmacfarlane.net/pandoc/ I edit in Emacs, but you can use whatever obviously.
网页和纸质输出的排版能力差距很大，选工具链时要接受“一种源文件、两种输出”的质量妥协。
他说自己用基于 docbook 的工具链（git-scribe 似乎就是这种）做不出高质量的 PDF。HTML 输出可以用 CSS 轻松定制样式，数学公式可以放进字面块，再用 MathJAX 在读者阅读时渲染。PDF 就麻烦得多：docbook 的 PDF 后端是 dblatex 或 fop。fop 开箱可配置的参数多，但不支持连字，数学排版也有问题；dblatex 输出质量更好，但 XML 样式表的可配置性有限，要调整就得写 LaTeX 的 sty 文件，比写 CSS 难得多。docbook 的好处是能用 XML 样式表转换成单页或分页的 HTML。其他替代方案也不多：Texinfo 能生成单页 HTML、分页 HTML 和 PDF，但 PDF 样式几乎不能改；Troff 支持 PDF，可它的 HTML 后端都很差；LaTeX 的 HTML 生成器也不太行。他觉得网页和纸质这两个目标之间的差距太大，很难用一套流程同时做出高质量的两者。
tbirdz查看英文原文
I haven't been able to get good quality PDF output using the docbook based toolchain, as seems to be used in git-scribe. You can style the HTML output with css easily, and you can even get good looking math by including your LaTeX in a literal block, and use MathJAX in your HTML template to generate the math when the reader looks at it. PDF however is a different story. Currently, docbook's PDF backends use dblatex or fop. Fop is more styleable out of the box, having many parameters you can set. However, fop doesn't support ligatures in the output, and has some issues with math typesetting. dblatex has better quality output, but the amount of configurability of the xml stylesheet is limited. In order to configure the output, you must write a LaTeX sty file, which is much more difficult than a css stylesheet. A nice thing about docbook is it has xml stylesheets to transform to split page HTML and single page HTML. Honestly though there's not really many alternatives. Texinfo can produce single page HTML, split HTML, and PDF, but offers very little PDF styling. If you want your output to look like a GNU Manual you are set, but even things like changing fonts are not supported. Troff supports PDF, but even though there are some HTML backends, they are all pretty bad. There are also some html-generators for LaTeX, but they aren't really that good either. I think there is just too much of a gap between web and paper targets to be able to generate both in high quality from a single source. It may be possible, but it is difficult, and current tools are not able to do this. honestly, I would love to be wrong about this conclusion, and if anyone knows of any other tools that can do this with good quality, please let me know.
把文档当代码来持续构建和发布，是已经被验证过、值得推广的写作工作流。
他说这正是他们在 readthedocs.org 为开源项目搭建的工作流。这个流程非常好用，写文档和写书都变得很轻松。他希望 asciidoctor 也能有一个标准化的站点构建模板，这样就能像支持 reStructuredText 和 Markdown 那样支持它。
forsaken查看英文原文
This is basically the same workflow we've been building at https://readthedocs.org, but for open source projects. It is really an amazing workflow, and makes writing documentation as well as books a breeze. I would love to see a standardized site building template for asciidoctor, so that we could support it as well as reStructuredText and Markdown.
自动构建解决的是效率问题，排版质量还得靠专门针对输出格式设计的工具，比如 softcover。
他很喜欢持续构建这个思路，但觉得生成的 PDF 排版质量并不算好。在他看来，技术写作的未来更像是 softcover（github.com/softcover/softcover），也就是 mhartl 那套基于 Markdown→LaTeX 的构建脚本。
ivan_ah查看英文原文
I really like the idea of a continuous build system, but I find the PDF produced is not super well typeset. If you ask me, the Future of Technical Writing looks more like this: https://github.com/softcover/softcover , mhartl's (markdown-->latex)-based build scripts
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选