技术写作与文档2019asciidoctor.org
Asciidoctor：快速的开源文本处理与出版工具链
Asciidoctor – A fast, open-source text processor and publishing toolchain
导读
这篇介绍 Asciidoctor——一个开源的 AsciiDoc 文本处理与排版工具链，评论区实际在讨论「写作者该选哪种标记语言」。值得一读，因为几位有实际写作经验的评论者（其中一位用它写完了整本书）给出了选型的第一手判断：能力与复杂度如何权衡、源码可读性为什么重要。
可以直接用的写作要点
- 01
标记符号的多少应与层级重要性一致：若三级标题比一级标题占用更多符号，读者扫源码时会误判文档结构。
- 02
AsciiDoc/DocBook 语义强、适合真正要印刷成书的项目；只是写一般文档，Markdown 已够用，别为工具过度设计。
- 03
动手前先查清所选格式的特殊字符转义规则（如 C++），否则正文会被解析器吞掉或渲染出错。
- 04
格式迁移不必纠结：用 pandoc 之类的转换器在 Markdown、reStructuredText、AsciiDoc 之间互转即可。
HN 评论精选
标记数量应与标题层级的重要性成正比，否则源码本身会误导读者对结构的判断。
标记语言和转换方案多得数不清，看看 pandoc 的 to/from 选项就知道了。我个人更偏爱 reStructuredText，相比各种 Markdown 方言含混不一的实现，它的设计感觉更一致。AsciiDoc 让我不舒服的一点是：低层级标题反而占用更多标记符号——视觉上「=== 这个标题」看起来比「== 这个标题」更重要。另外 hyperpolyglot.org/lightweight-markup 上有一份很好的横向对比。
smartmic查看英文原文
There are so many markup languages and conversion possibilities, just have a look on the to-from option from pandoc. Personally, I prefer reStructuredText, its design feels more consistent in comparison to the ambiguous implementations of the various markdown dialects. In Asciidoc, I do not like that lower lever headings occupy more markers than higher level ones. Visually, === This heading appears more important than == This heading By the way, a good comparison is at http://hyperpolyglot.org/lightweight-markup
功能强大的格式也意味着复杂度高，一般文档用 Markdown 更划算。
AsciiDoc 是一种人类可读的文档格式，语义上等价于 DocBook XML，只是用纯文本标记约定。Asciidoctor 则是处理 AsciiDoc 的工具链。要注意的是 AsciiDoc 语法极其复杂，因为它映射到本身就相当复杂的 DocBook 标准；它有一大堆花哨功能，做一本真正要印刷的书时也许用得上，但写一般文档就未必。我觉得如果你写的不是真要付印的东西，AsciiDoc（和 DocBook）就是杀鸡用牛刀。
emmanueloga_查看英文原文
"AsciiDoc is a human-readable document format, semantically equivalent to DocBook XML, but using plain-text markup conventions." And Asciidoctor is a toolchain for working with AsciiDoc. One thing to have in mind is that AsciiDoc syntax is incredibly complex [1]: it maps to the already complicated-on-its-own-right DocBook standard [2]. It has a lot of bells and whistles that one may want to use on a real print book, but maybe not for general documentation. I feel like if you are not writing something that you actually intend to print, Asciidoc (and DocBook) are overkill. 1: http://asciidoc.org/userguide.html 2: https://docs.oasis-open.org/docbook/docbook/v5.1/os/docbook-v5.1-os.html
长篇写作可以用更强的格式，但要先摸清它的转义与特殊字符规则。
我用 AsciiDoc 写了一整本书（链接：book.picheta.me）。这是个很棒的工具，比 Markdown 强大得多，但确实有些怪癖，比如你必须转义「C++」。
dom96查看英文原文
I've written my book in Asciidoc [1]. It's a brilliant tool and far more powerful than Markdown but it does have some quirks (for example, you need to escape "C++"). 1 - https://book.picheta.me
对愿意投入一点学习成本的人，AsciiDoc 可以在不牺牲易用性的前提下换来更强表达力。
我已经完全用 asciidoctor 替代了 Markdown，写文档和一般写作都用它。它比 Markdown 强得多，用起来同样简单，GitHub 也支持。
gouggoug查看英文原文
I've entirely replaced markdown and been using asciidoctor for both documentation and general writing. Asciidoctor is far superior to Markdown and as easy to use and is also supported on Github.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选