[支える技術]エクセルやパワーポイントのドキュメントを捨てて、超美麗なドキュメント作成をasciidoctorで実現しよう!

スポンサーリンク
スポンサーリンク

開発には付き物のドキュメント作成、現場ではワードやエクセル、パワーポイントを使うことが普通ですよね?
そんなドキュメント作成に革命を起こしそうなのがasciidoctorです。
Office製文書の悪い問題を簡単に解決してくれます。

Officeで技術文書を作成する時の問題点

  • 成果物がバイナリなので Git などのバージョン管理ツールと相性が悪い
  • 内容以外の修飾に掛かる時間が膨大すぎる、ワード以外では目次の作成、章番号の連番付け、印刷結果との違いの確認など 文章の内容を記述する時間より、体裁を整えるのに時間が掛かる
  • Windows以外ではなかなか編集できない
  • コードのハイライトなどできない
  • コピーペーストがままならず同じパワポ同士でもテンプレート元が違うと体裁が崩れてしまう
    などなど、問題山盛り手間がかかりすぎです。

もっと手軽にバージョン管理ができて、 体裁も綺麗な ドキュメントを 簡単に 作りたい!!

asciidoctorがめちゃめちゃお勧めです!

asciidoctorは、AsciiDocというMarkdownとかと同じようにテキストフォーマットで書いてHTMLやPDFに変換できるRuby製のツール群です。

メリット

  1. 変換元がテキストファイルであるため、バージョン管理ツール GIT との相性がよい
  2. include機構があるため、共通化しやすくメンテナンス性が良い
  3. 目次な章番号など自動で割り振りするためメンテナンス性が良い
  4. ソースコードをハイライトする機能や行番号の付与など自動で行ってくれる
  5. 図やテーブルもテキストで記述可能である
  6. マークアップで出力されるフォーマットが決まるため、書式の統一化を行いやすい

デメリット

  1. 変換処理が必要であるため、変換機構を自動化する仕組みがないと不便
  2. 図が直感的にイメージしづらい場合がある
  3. フォーマットがある程度固定であり、自在に編集可能というわけではない

導入は超簡単!

ここから下はGistに貼り付けたasciidoc文書で書きます。