ドキュメント作成ツールの検討(Sphinx、ReVIEWとか)
今後、マニュアルを書いてメンテナンスも継続的にしていく機会が丁度ありそうなので、現時点(2012/05/02)でどのツールが自分たちにフィットするか検討してみた。ツールの候補は以下。なお、過去の仕事ではWordとDocBookは経験あり。
前提
今回のマニュアル作成の前提は以下の通り。
- 複数人で作業し、1つのドキュメントを作成する(主に章単位でアサイン)。
- 特定顧客向けに部分的にカスタマイズして提供することもある。
- 外部向けのドキュメントなので、体裁はそれなりに整っている必要がある。
- 製品のエディションによってマニュアル構成が変わる(上位のエディションだと機能が増えるので章や節、説明が増えるなど)。
- 出力フォーマットはWordまたはHTMLならOK。PDFは必須ではない。
- ドキュメント中に画像はそれなりにある。スクリーンキャプチャ、構成図みたいなダイアグラムもある。
- ドキュメント作成者のメインPCはWindows。
- ドキュメント作成者はプログラマやインフラ担当などの技術者で、コンピュータリテラシーは高い。
Word
知らない人はほとんどいないであろう、Microsoft社のWord。
Wordの良い点:
- 初心者にもとっつきやすく書きやすいUI。
- 日本語の文法チェック機能、文章校正の機能がある。
- ツールを切り替えることなく文章中に図を作成することができる。
Wordの残念な点:
- プレインテキストではないのでGitなどのバージョン管理ツールとの相性が悪い。
- 採番機能はあるがよくずれるため当てにならない。
- 1ファイルに大量に記述すると、良く落ちるようになったり開けなくなったりする。これは回避方法として、章単位にファイルを分割するといった方法がある。というか、分割しないと複数人で作業しづらいので、分割はした方が良い。分割したファイルから目次を生成する機能がWordにはあるのでこちらを使おう。
- 自由に書き易い分、スタイルの統一が大変。特に複数人で1つのドキュメントを作成する場合。スタイル機能をちゃんと使いこなす必要が出てくるのだが、難易度がグンと上がる。
- たとえスタイル機能を使っても、スタイルの適用をミスっていたりすると目視で確認するのが大変(よ〜く見ないと分からないとか)。前の仕事では、スタイルのミスを見つけるために人力でひたすらマニュアルのスタイルチェックを行っていました。画面では確認しにくいため印刷してチェックするとか、紙の無駄遣いにもなっていた。
- その他、デフォルト設定だと使いづらく色々とカスタマイズした方が良い(標準だとおせっかいすぎるので)。以下の本を見て使いこなすのがおすすめだが、これを全利用者に個別に設定してもらうのも一苦労。
エンジニアのためのWord再入門講座 美しくメンテナンス性の高い開発ドキュメントの作り方
- 作者: 佐藤竜一
- 出版社/メーカー: 翔泳社
- 発売日: 2008/05/22
- メディア: 単行本
- 購入: 49人 クリック: 1,686回
- この商品を含むブログ (94件) を見る
DocBook
DocBookは技術文書のためのマークアップ言語で、XMLでドキュメントを作成していきます。XMLからHTML、PDF、manページ、HTMLヘルプなどを生成することができる。
DocBookについては2008-2009年頃に使用していたことがあり、ブログにも書いていた。当時はEclipseのXMLエディタでドキュメントを書いていたが、XMLスキーマを読んで検証もしてくれるし、補完もOKで、バージョン管理ツールも統合されているので便利だった。
- Mavenを使った簡単DocBook入門 - Hirohiroの日記
- マニュアルは何が良いか - Hirohiroの日記
- 意外と乱立しているmaven-docbook-plugin - Hirohiroの日記
- PDFへの変換 - Hirohiroの日記
- Visual DocBook Editorを試してみた - Hirohiroの日記
DocBookの良い点:
DocBookの残念な点:
- XMLなのでどうしても記述が冗長になりがち。特にリストとか表とか。コンピュータには優しいが人間には余り優しくない。
- 図は画像ファイルとして管理する必要がある。Wordのようにシームレスに扱えない。また、JPGとかPNGで管理しちゃうと、オブジェクトのレイヤー情報が失われてちょっと位置をずらすとかの修正も大変。Visioなど別ツールのファイルでオリジナルを管理する必要が出てくる。
- 出力フォーマットのスタイルカスタマイズが大変。DocBookではXSLTでXML->HTMLに変換しているのだが、XSLTが難解すぎる。
- ドキュメント生成環境を構築するのに一苦労(今だと改善されている？)
- 日本語のPDF作成に難あり(今だと改善されている？)
Sphinx
Python製のドキュメント生成ツールです。DocBookとは異なり、XMLではなくreST(reStructuredText)記法でドキュメントを作成します。DocBookと同じように、1つのソースからHTML、PDF、ePubなどを生成することができる。
Sphinxの良い点:
ReVIEW
Ruby製のドキュメント生成ツール。名前がSEO的に微妙でググってもヒットし辛いのが難点。参考サイトへのリンクを記載しておきます。
- ReVIEWクイックスタートガイド
- はじめてのReVIEW〜InDesignへの取り込み - 名もないテクノ手
- ReVIEW の使い方 - A Day in Serenity @ Kenji
- 1つのソースでEPUBとPDFを生成できる「ReVIEW」を試す - builder]
こちらもSphinxと同様に、XMLではなくWiki に似た簡易フォーマットでドキュメントを記述していく。出力も同様に、HTML、PDF、ePubなどに対応。
ReVIEWの良い点:
- プレインテキストで記述できるためGitなどのバージョン管理ツールと相性が良い。
- プレインテキストなので軽量。サクサク書ける。
- XMLではなくWikiっぽい記法なので人間にも優しい。
- 秀丸での編集支援マクロがありWindowsユーザでも書きやすそう。
- 環境構築も比較的容易。
結論
結論としては、今回はSphinxを選択する予定。
理由
- Wordはバージョン管理との相性が最悪なのが一番痛い。あと、スタイルを統一するという点にすごいパワーがかかる(前の仕事で身を持って経験済み)ので外した。
- 製品エディションでマニュアル構成が変わるのだが、共通部分は二重管理したくない。Wordだと動的な構成に対応するのは厳しい。ここはDocBook、Sphinx、ReVIEWであればプログラムで操作できるので対応しやすいはず。
- DocBookは個人的にはなれているのだが、技術者がドキュメントを書くとはいえ、今後継続的にメンテナンスして行くことを考えると、人に優しいWiki的な記法が望ましい。
- ReVIEWも記法としてはシンプルで魅力的だが、出力フォーマットが出版メインでHTMLだと現時点では貧弱。
正直なところ、Sphinx、ReVIEWの2つは全然使いこんでいないので、今後落とし穴にハマる可能性はあるが、新しいことにチャレンジするのも大切なのでいい機会と思って頑張ってみます。
