開発には付き物のドキュメント作成、現場ではワードやエクセル、パワーポイントを使うことが普通ですよね？
そんなドキュメント作成に革命を起こしそうなのがasciidoctorです。
Office製文書の悪い問題を簡単に解決してくれます。
Officeで技術文書を作成する時の問題点
- 成果物がバイナリなので
Gitなどのバージョン管理ツールと相性が悪い - 内容以外の修飾に掛かる時間が膨大すぎる、ワード以外では目次の作成、章番号の連番付け、印刷結果との違いの確認など 文章の内容を記述する時間より、体裁を整えるのに時間が掛かる
- Windows以外ではなかなか編集できない
- コードのハイライトなどできない
- コピーペーストがままならず同じパワポ同士でもテンプレート元が違うと体裁が崩れてしまう
などなど、問題山盛り手間がかかりすぎです。
もっと手軽にバージョン管理ができて、 体裁も綺麗な ドキュメントを 簡単に 作りたい！！
asciidoctorがめちゃめちゃお勧めです！
asciidoctorは、AsciiDocというMarkdownとかと同じようにテキストフォーマットで書いてHTMLやPDFに変換できるRuby製のツール群です。
メリット
- 変換元がテキストファイルであるため、バージョン管理ツール
GITとの相性がよい - include機構があるため、共通化しやすくメンテナンス性が良い
- 目次な章番号など自動で割り振りするためメンテナンス性が良い
- ソースコードをハイライトする機能や行番号の付与など自動で行ってくれる
- 図やテーブルもテキストで記述可能である
- マークアップで出力されるフォーマットが決まるため、書式の統一化を行いやすい
デメリット
- 変換処理が必要であるため、変換機構を自動化する仕組みがないと不便
- 図が直感的にイメージしづらい場合がある
- フォーマットがある程度固定であり、自在に編集可能というわけではない
導入は超簡単！
ここから下はGistに貼り付けたasciidoc文書で書きます。
コメント