“写作很难。”
经验让我们相信了这一点。
但是，我们不能仅仅避免它，特别是在科技行业。我们必须要写作。即使是最杰出的软件没有好的文档也是没有用的。如果用户失败了，项目也就失败了。
除非你的用户界面可发现性*非常好*，否则说“功能没有文档”就等于是说“产品做不到这一点”。
换句话说，
凭借文档来生存和灭亡。
那么，为什么我们还要让事情变得更复杂，通过将内容埋藏在像DocBook这样的XML模式中，让复杂的文字处理软件分散我们的注意力，或浪费时间与难以驾驭的所见即所得编辑器作斗争呢？
想象一下，如果编写文档就像写电子邮件一样简单。
它可以是。
这就是轻量级标记语言如AsciiDoc背后的理念。它们提供了一种纯文本的语法，用细腻而直观的标记进行装饰，旨在让人们以原始形式阅读、编写和编辑。语法的自然感觉让你专注于内容。最重要的是，纯文本可以快速轻松地转换成如HTML5等输出格式，以便展示。
在这个AsciiDoc的介绍中，我们将讨论它是什么，为什么它有价值，以及它与Markdown等替代方案的不同之处。你会发现，摆脱编写文档之苦的关键是放弃那些埋葬你需要分享的知识的角括号。
要了解如何减少撰写和发表内容的工作量——无论是笔记、文档、文章、书籍、网页还是传统的散文——以及达到写作禅境，或者仅仅是释放你脑中锁定的想法，请继续阅读。
AsciiDoc是什么？
AsciiDoc 是两样东西：
-
一个成熟的[1]，纯文本写作格式，用于撰写笔记、文章、文档、图书、电子书、网页、幻灯片集、博客文章、手册页等。
-
一个文本处理器和工具链，用于将AsciiDoc文档翻译成各种格式（称为_后端_），包括HTML、DocBook、PDF和ePub脚注：[有两种实现AsciiDoc处理器的方法。原始的处理器，命名为AsciiDoc，是用Python编写的。一个更现代的实现，名为Asciidoctor，是用Ruby编写的。]。
AsciiDoc 属于 轻量级标记语言家族，这个家族最著名的成员是 Markdown。与这一组语言相比，AsciiDoc 引人注目之处在于它支持编写文章、技术手册、书籍、演讲和散文所需的所有结构元素。事实上，它能够满足甚至是最高级的出版要求和技术语义。
作为这一事实的证明，许多 O’Reilly 的作者，包括 [Matthew McCullough](Tim Berglund(Simon St.Laurent(Matt Neuburg(https://www.apeth.net/matt/iosbooktoolchain.html) 和 [Ian Darwin](https://www.oreilly.com/pub/au/219) 都使用 AsciiDoc 来撰写他们为那个标志性技术图书馆出版的图书。
从一开始，AsciiDoc 就被设计成为 DocBook 的简写替代方案，DocBook 是 AsciiDoc 可以生成的格式之一。AsciiDoc 还可以制作精美的 HTML5、PDF、电子书、手册页甚至幻灯片。从初稿到出版，它都能满足你的需求。
现在我们已经明确了AsciiDoc是什么，接下来让我们考虑为什么我们需要它。
为什么选择AsciiDoc？
作为人类，我们在谈话或思考时没有任何困难。事实上，我们在这方面很流利。每当一个想法涌现到脑海时，这一活动就会自然发生。
另一方面，写作很少那么容易。
当我们需要把我们的思绪写下来时，我们努力寻找合适的词汇——或者至少是如何安排和组织它们。那个该死的内心批评家打断了我们在谈话或思考时依赖的意识流。
可以合理地得出这样的结论：写作就是困难的。
它是这样的吗？
关于写作：电子邮件与文档比较
撰写电子邮件很简单。我们经常这样做。每天，我们都要回复几十封电子邮件和社交媒体消息。那涉及到通过写作进行沟通。没错，就是_写作！_
然而，在我们回复电子邮件时急促的敲击键盘之中，我们几乎甚至没意识到我们正在进行的是…并且_流畅地!_
原来如此……
大多数人对写电子邮件没什么意见。他们不认为那是写作。没有写作障碍。有人问你问题，你点击回复然后随手打出来。
为什么我们在写*文档*时会感到困难？
我们之所以遇到困难，主要是因为我们写文件的方式与写电子邮件的方式不同。相反，我们允许自己被复杂的文字处理器分散注意力，把内容深埋在像DocBook这样的XML架构中，或者与挑剔的所见即所得编辑器作斗争。我们是怎么陷入这种困境的？
文字处理软件，真正的作家障碍
当你处于写作（即打字）阶段时，你希望文字能够顺畅地流入屏幕，尽可能少的干扰和中断。流畅性，而不仅仅是时间，是至关重要的。
大多数文字处理软件擅长于分散你写作的注意力。结果：你写得更少了（讽刺吧？）。
在文字处理软件中，在您能在空白白色屏幕上打出第一个单词之前，您被迫思考您想要什么字体家族、什么字体大小、什么行距等等。一旦您开始输入，自动纠错、拼写和语法建议吸引您回头修改，导致您失去接下来的思路。“智能”引号和自动链接功能在您输入文本的同时搅乱文本。如果您粘贴文本，它可能会以不同的字体家族、大小甚至颜色被添加到文档中。
撤销。撤销。撤销！
我们甚至不要谈论插入源代码。文字处理器的设计者显然没有。
格式化。格式化。格式化！
在与其界面进行了一番旷日持久的斗争后，你完全有理由得出结论：这个文字处理器正在试图_破坏_你的写作过程。
我们需要一种更简单的写作方式！
但是怎么做？
运用你所知道的
如果你能像写电子邮件一样编写文档会怎样？
想象一下能够忘记布局、排版、样式（甚至一些语义）只需要_写作_。这就是*轻量级标记语言*如Markdown和AsciiDoc背后的理念。
约翰·格鲁伯在2004年3月是这样介绍 Markdown 的：
Markdown格式语法的首要设计目标是使其尽可能可读。
一个Markdown格式的文档应该能够直接发布，就像纯文本一样，看起来不像是被标签或格式化指令标记过。
Markdown 语法的最大灵感来源是纯文本电子邮件的格式。
同样，这是斯图尔特·拉克汉（Stuart Rackham）在2年前介绍AsciiDoc的方式：
你撰写AsciiDoc文档的方式与你编写普通文本文档的方式相同。没有标记标签或奇怪的格式注释。AsciiDoc文件的设计初衷是可以直接查看、编辑和打印，或转换为其他展示格式。
这些语言的设计初衷是让人类能够编写文档，并且让其他人能够以其原始形式“按原样”阅读它们。
这是一个AsciiDoc文档的基本示例：
= AsciiDoc 介绍
Doc Writer <doc@example.com>
关于https://asciidoc.org[AsciiDoc]的前言。
== 第一部分
* 项目 1 * 项目 2
[source,ruby] puts "Hello, World!"这是一个纯文本语法……我*知道*这个！
将其与用DocBook编写的同一文档进行比较：
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<article lang="en">
<articleinfo>
<title>Introduction to AsciiDoc</title>
<date>2013-01-01</date>
<author>
<firstname>Doc</firstname>
<surname>Writer</surname>
<email>doc@example.com</email>
</author>
<authorinitials>DW</authorinitials>
</articleinfo>
<simpara>
A preface about
<ulink url="http://asciidoc.org">AsciiDoc</ulink>.
</simpara>
<section id="_first_section">
<title>First Section</title>
<itemizedlist>
<listitem>
<simpara>item 1</simpara>
</listitem>
<listitem>
<simpara>item 2</simpara>
</listitem>
</itemizedlist>
<programlisting language="ruby"
linenumbering="unnumbered">
<![CDATA[puts "Hello, World!"]]>
</programlisting>
</section>
</article>哎呀！
虽然DocBook（和HTML）可能并不复杂，但它们没有通过可读性测试。
DocBook很不错，但（就像XML一样）它不是用于编辑的，也不适合合并（人类的）修改。使用AsciiDoc（它能完美转换为DocBook）是一个开发过程中更加简便的方式。
AsciiDoc让我们回归到重要的事情上：写作。你可以放弃那些尖括号，但你不必放弃语义。而且它是一种人类可以实际编辑的、高效的语法。
使用AsciiDoc进行文档标记。真的。它对人类来说实际上是*可读的*，比XML更容易解析且更加灵活。
AsciiDoc 真正好的地方在于，最坏的情况下，你可以将其转换为常用的交换格式 DocBook。DocBook 是 AsciiDoc 的“无锁定”退出路径。你觉得 AsciiDoc 不适合，可以退出而不丢失任何内容。无需发明另一种格式。这就是为什么这么多人全力以赴的原因。
谁在使用AsciiDoc？
AsciiDoc没有Markdown那么广泛使用，但它在一些非常重要的地方被使用。以下是一些值得注意的例子：
-
GitHub支持在仓库、维基和代码片段中使用AsciiDoc语法（由Asciidoctor提供支持）
-
NFJS, the Magazine is produced from articles written in AsciiDoc
-
Java EE平台的上下文与依赖注入 (CDI)
-
官网 (AsciiDoc源码)
这些例子不仅仅是推荐信。它们应该能给你关于如何在你自己的项目中成功使用AsciiDoc的灵感。
写作AsciiDoc的禅意
AsciiDoc的核心在于能够专注于表达你的想法，轻松写作并传递知识，而不会被复杂的应用程序或尖括号分心。换句话说，它是关于发现_写作的禅意_。
AsciiDoc有效的原因是：
-
它是可读的
-
它很简洁
-
它是全面的
-
它是可扩展的
-
它能生成漂亮的输出（HTML, DocBook, PDF, ePub等等）
AsciiDoc编写简单，即使是在原始形态下也易于阅读。它也便于校对和编辑。毕竟，它是纯文本，就像那些熟悉的电子邮件。
AsciiDoc 语法直观易懂，因为它识别了历经时间考验的、用于标记或结构化文本的纯文本约定。标点符号的选用经过仔细考虑，看起来就像它所表达的含义。不熟悉 AsciiDoc 的用户通过观察也能弄清楚文本的结构和语义（即你想表达的意思）。最重要的是，阅读或写作只需要一个文本编辑器。
AsciiDoc允许您专注于实际的写作，只有在准备转换文档时才担心调整输出。AsciiDoc文档的纯文本很容易被转换成各种输出格式，并且无需重写内容即可美观地格式化。
将电子邮件中的文本复制到文档中，看看你能多快将其转换成文档。几乎立刻，你就会找到你写作的禅意，并享受分享知识带来的愉悦体验。
通过文档的力量生存还是死亡？
“活下去！”
下一步操作
了解了AsciiDoc是什么以及为什么它如此迫切需要后，你将被鼓励深入了解链接:/docs/asciidoc-writers-guide[AsciiDoc Writer’s Guide]中介绍的AsciiDoc语法。如果你只是在寻找一个速查表，可以查看https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[AsciiDoc Quick Reference]。希望你会同意这种语法只是讲得通。