AsciiDocを利用してエンジニアのナレッジを上手に集約しよう | cloud.config Tech Blog

はじめに

流用性・検索性が高いドキュメントの作成は今後のエンジニアに求められるスキルの一つです。
一方で社内ではPowerPointやWordによるドキュメント作成が頻繁に行われる事が多いのではないでしょうか？PowerPointやWordは即時性が高いフォーマットですが、流用性・検索性を確保し続ける事が困難です。
エンジニアが気軽に出版レベルのドキュメントを作成したり、Wikiより管理の容易なナレッジを作成するのに役立つAsciiDocをご紹介するとともに、より柔軟な運用について提案したいと思います。

AsciiDocとは

AsciiDocは軽量マークアップ言語の一つで可読文書記述形式です。
出力もHTML, PDF, ePubなどが行えるため個人での出版活動から開発環境でのナレッジの共有まで様々な用途で利用する事が可能です。

AsciiDocの記述方法

軽量マークアップ言語でメジャーなフォーマットにはmarkdownがあります。AsciiDocはmarkdownと比較し同様の記述容易性を供えつつもより高度な文書の論理構造を構築する事が可能です。
例えば以下のような記載方式で文書を記載する事ができるため、ワードのように書式の設定に悩まされることはありません。

= ドキュメントのタイトル

本ドキュメントは、、、

== レベル１のセクションのタイトル

レベル1の内容、、、

=== レベル２のセクションのタイトル

* リストレベル１
** リストレベル２
*** リストレベル３


== 別のレベル１のセクションのタイトル

- [x] チェック済みチェックボックス
- [ ] 未チェック

以下はリンクの書き方です。
http://asciidoctor.org[AsciiDoctor]

詳しい記述方法は割愛しますがAsciiDocで記載された以下のサイトを参考に記述すれば簡単にドキュメント作成できることを実感いただけるのではないでしょうか。

AsciiDoctor 文法クイックリファレンス(日本語訳)

AsciiDocを利用すべき理由

AsciiDocはテキストエディタで記述でき可読性が高いことや、コードと同様にGit等でのバージョン管理も容易でエンジニア親和性が非常に高いことが特徴です。
Gitでバージョン管理を行えば複数人数で頻繁な編集を行う際のマージ等も円滑に行うことができますし、Pull Requestを利用した校正など高度な編集環境が気軽に構築可能です。また一つのドキュメントを作成するにあたり、複数のファイルをインクルードする形で作成する事が可能です。
またGitHubではREADMEを.adocで作成した場合、.mdと同様にリポジトリページでプレビューする事が可能ですから、普段から気軽に使えることもポイントです。

社内ドキュメントとの共存

テキストエディタで記述できるAsciiDocの導入に踏み切れない事情として社内ドキュメントがPowerPointやWord、Excelなどで作られている事が挙げられます。
確かに、PowerPointで書く内容を全てAsciiDocで表現できませんしPowerPointのようなプレゼン資料にはパッと見で概要を納得させる大きな力があります。Wordのように事務部署が編集に慣れたフォーマットも、そのまま計算できるExcelにもAsciiDocはかないません。
しかし、AsciiDocにはリンクがあります。引用元の資料へのリンクを貼ることで既存の資料を大きく拡張する事ができます。
PowerPointの重要な1ページを画像で貼り付け、Html書き出ししたものをWord化し、計算のいらない表はAsciiDocで記載できます。

これによりPowerPointにかかれない詳細の仕様や背景を詳細に記録したり、各テキストを再利用したり、正しい使用を明確に記載し共有する文化を作る事ができます。
PowerPointやWord、Excelなどを正しい使い方で利用しつつ、エンジニアがさらに便利になるような使い方をAsciiDocで行うことができます。

編集中のAsciiDocをプレビューするには

編集中にAsciiDocをプレビューする方法は実はあまり多くありません。
しかし可読性が高いことを踏まえた上で以下の選択肢を見れば実際に利用する上で大きな問題にならないと感じるのではないでしょうか？

Atom : GitHubが開発したオープンソースのテキストエディタでElectronを利用し作成されています。AsciiDocのプレビューにはAsciiDoctorのパッケージ「asciidoc-assistant」を利用します。
Visual Studio Code :: Microsoftが開発したテキストエディタでElectronを利用し作成されています。Atomからの派生ではなく、Visual Studio Online のエディタ（コードネーム "Monaco"）が基になっています。AsciiDocのプレビューにはAsciiDoctorが提供するextensionとして「AsciiDoc」を利用します。

AsciiDocでHTMLやPDF等を出力するには

AsciiDocでHTMLを出力するにはAsciiDocコマンドもしくはAsciiDoctorコマンドを以下のページの方法でインストールする方法があります。

これらの出力環境を自分で構築し運用したい場合もあると思いますが、「流用性・検索性が高いドキュメントの作成」を目的とした場合、多くの人が環境を維持するためのコストを小さくしたいと思うのではないでしょうか？
次回は複数人で気軽に編集してHTMLやPDF等を出力する環境を簡単に構築できる方法をご紹介したいと思います。