成为软件开发人员最不寻常的方面之一是涉及大量的写作。 不只是软件编写，而且：
- 文献资料
- 技术提案
- 实例探究
- 征集论文
- 网志
编写软件总是意味着要解决一个非常人性化的问题，并且向其他人（尤其是那些不是软件开发人员的人）表达人为问题的方式是从字面上讲的。
k牛刮我的笔迹
对我来说，作为一个软件开发人员，过去通常在诸如code ， vim编辑器中完全使用等宽字体，或者当我不得不将其拔出时， IDEA编写提供了许多不幸的选择。
一个可以选择：
- 字体
- 字体大小
- 边距高度
- 航向高度
- 页面结构
- 代码风格
- 报价风格
- …
基本上是无数个东西。 同样，鉴于专业背景，我花了大量时间来使这些文档集“恰好” —却不知道“恰好”是什么样子。
问题是，尽管我得到的文件漂亮得可疑，但我得到的文件也很空白。 写作或编码时大脑所涉及的创造性部分与我执迷于标题的蓝色阴影所使用的部分完全不同。 更糟糕的是，它们是互斥的，与我实际编写内容相比，我显然更喜欢使用蓝色字体进行调整。
顺便说一句，这就是为什么中号是一个如此神奇的写作场所的原因-缺乏选择使写作成为内容的重中之重，而不是该死的蓝色标题。
解决选择悖论
自主和选择自由对我们的福祉至关重要，而选择对于自由和自主至关重要。 尽管如此，尽管现代美国人比以往任何人都有更多选择，因此，据推测，自由和自治更多，但我们似乎从心理上没有从中受益。
—摘自《选择的悖论》 （2004年）第5章
当文档演示几乎完全没有我的想法时，我的写作就会成功得多。 像：
- Git承诺
- 中篇文章
- 纯文本电子邮件
- 降价促销
一切都顺畅，轻松地进行。 但是针对客户的关键建议总是迟迟未获通过。
解决方案不是更多，而是更少。 阿西奥多！ 从asciidoctor.org网站：
想象一下编写文档是否像编写电子邮件一样简单。
可以 。
这就是诸如AsciiDoc之类的轻量级标记语言的思想。
Asciidoctor是以下各项的组合：
- 句法
- 工具链
学习辅助
Asciidoctor基本上是Markdown的超集。 我使用的语法是：
=标题1
==标题2
===标题3
这是段落文本。 我通常以120个字符将其分解，因为
我喜欢艰苦的工作，并且从开发中就习惯了。
>这是一个报价。 演示文稿中的引号看起来不错；
>非常重要。
[ditaa，target =“ a-diagram”]
....
+ -------- + + ------- + + ------- +
| | -+ ditaa +-> | |
| 文字| + ------- + |图|
|文档| |！魔术！| | |
| {d} | | | | |
+ --- + ---- + + ------- + + ------- +
：^
| 很多工作|
+ ------------------------- +
...
结合命令：
$ asciidoctor --require ='asciidoctor-diagram'example.adoc
产生非常漂亮的HTML
而已！ 您学会了asciidoctor。 还有一些更酷的功能，但这足以编写大量的技术文档。
寻找新的牛剃须
尽管Asciidoctor确实比Google Docs，Microsoft word或LibreOffice（我要向您推荐）更是一项巨大的改进，但仍有一些值得探讨的地方。
酸度-pdf
如前所述，asciidoctor可以输出多种格式。 从--help命令行标志：
[html5，xhtml5，docbook5，docbook45，手册页]（默认值：html5）
但是，我无法与所有项目利益相关者分享我对手册页的热爱。 相反，他们喜欢PDF。
Asciidoctor发布了一种可直接导出为PDF的工具，可预测地称为“ asciidoctor-pdf”。 它生成精美的排版，结构良好的PDF文件供使用：
这些非常漂亮，但是可以使用asciidoctor PDF主题快速进行自定义。 这些生成精美品牌，专业外观的PDF：
它们也非常一致，是从本质上纯文本生成的，有些难以修改。
安托拉
Antora是用于根据asciidoctor原语编写文档的一组工具。
对于文档的布局方式，人们非常有意见，但可以将来自不同来源的文档组合到一个单一的，具有凝聚力的网站中：
Antora用于几个项目，包括：
- 软呢帽
- 自己的云
- Couchbase
我自己对Antora的实验才刚刚开始，但确实提供了一些引人注目的好处：
- 专为有限的用户而设的高级文档，但需要大量现有软件和功能
- 在PDF和文档网站中重复使用相同的文档片段
- 受支持的Asciidoctor工具链
将来，它可能会非常有用，特别是对于将几个不同软件组件编译到自定义软件堆栈中的代理开发人员而言。
吉特
像大多数软件开发人员一样，我跟踪版本控制更改的结果。 尽管起初不是，但现在是一种非常自然的思维方式：
- 写一些文件
- 提交更改
- 要审查的主题文档
通过与更改代码相同的严格程度来处理文档，可以就事物应该如何工作以及它们为什么起作用的方式浮出水面。
这样的讨论可以极大地促进团队在理解系统或给定问题的方式上的一致性，并提高文档的质量，直到每个人都可以理解为止。
此外，能够在文档的历史记录中来回导航和使用代码一样有用，并且将文档保持在代码附近意味着随着代码的更改，文档也会更改，即使在同一PR中也是如此。
结论
去年，至少在我完成的写作方面，我的写作取得了更大的成功。 我的时间也许比以前少了，但是发现了一些工具，这些工具使编写任务比以前的定制尝试简单得多。
Asciidoctor提供了一种有前途的工具，它可以在书写的简单性与能够以多种不同但非常漂亮的方式表达该书写之间取得平衡。
10/10 Asciidoctor作者。
