はじめに

今月は技術学習をしないからってブログを書いちゃダメってわけじゃないんですがどうも滞ってますね。今年はドキュメント作成をクールでエレガントに！というすこぶる曖昧なテーマを掲げて活動しています。以下の本を読みました。

ドキュメント作成システム構築ガイド

githubでドキュメントを管理し、チームで開発する環境を整える。

次にredpenという構成ツールでドキュメントのテストをする。（赤ペン先生ですね。）

そしてコミットが起きるたびにredpenが動くようにTravisでgithubと連携する。

できあがったドキュメントをasciidoctorでpdfやhtml、epubに変換する。

おもにこの4つをコアに説明しています。

はてなブログもmarkdownで書けることでそもそもブログをたくさん書くようになりましたし、日常的にmarkdownを使っています。

asciidocについては以前より存在はしっていたものの、「改行が+は嫌や」という理由で避けていました。

この記事が良くまとまっています。

さて実際にasciidocを使ってみた感想ですが、多くの点でasciidocのほうが優れていると感じます。さらにmarkdownに慣れてるひとなら習得も容易です。実際に書きながらすぐに覚えることができると思います。

具体的にasciidocが優れている点は

といったところが大きいと思いました。特にcsvをそのままテーブルにできるのはかなりいいなと。markdownはテーブル結構めんどくさいよね。

簡単なメモはもちろんこれまで通りmarkdownで、少し大きめな、仕様書レベルだと絶対にasciidocがいいです。

1番気になるのは環境面ですよね。Atomにasciidoc-previewというプラグインがあるんですが、それはインストールに失敗しました。

今は普通のエディタで書いて、firefoxのアドオンでプレビューしています。リアルタイムプレビューではありませんが、十分かなと。chromeにもあります。（がchromeのほうは動作しませんでした。）

最期にasciidocで書いたadocファイルをhtmlやpdfに変換するには、asciidoctor、asciidoctor-pdfを使います。以前はpython実装のasciidocで変換できたみたいですが、後発のruby製のasciidoctorのほうが楽だったのでそちらをおすすめします。

これはmacかlinux環境が必要なので、windowsユーザにはいちいち持って行って変換するのが少しめんどくさいかもしれませんね。

gem installでいれて、コマンド叩くだけです。クッソ簡単。

asciidocでは NOTEやCAUTIONといった注意書きを書けます。これを書くと画像が出て欲しいんですが、デフォルトでは出ません。こんなやつです。

ページ右側の i のマークね。

asciidocのheaderのメタ部分に以下の記述を書けばokです

:icons: font

今ちょうど会社で新しいツールを作っていて、その仕様書兼マニュアルをasciidocで書いています。デフォルトの変換でhtmlもpdfも十分綺麗に書けて満足してます。

今後はasciidoctor-diagramを使ってUMLを書けるようになりたい。これができればもうシステム設計も完全にasciidocで書けることになる。そしてasciidoctor変換時にstyle(css)指定もできるようになりたいですね。部内で広げていきたいと思います。