ドキュメント作成ツールの検討(Sphinx、ReVIEWとか)

Word Sphinx ReVIEW DocBook

今後、マニュアルを書いてメンテナンスも継続的にしていく機会が丁度ありそうなので、現時点(2012/05/02)でどのツールが自分たちにフィットするか検討してみた。ツールの候補は以下。なお、過去の仕事ではWordとDocBookは経験あり。

前提

今回のマニュアル作成の前提は以下の通り。

  • 複数人で作業し、1つのドキュメントを作成する(主に章単位でアサイン)。
  • 特定顧客向けに部分的にカスタマイズして提供することもある。
  • 外部向けのドキュメントなので、体裁はそれなりに整っている必要がある。
  • 製品のエディションによってマニュアル構成が変わる(上位のエディションだと機能が増えるので章や節、説明が増えるなど)。
  • 出力フォーマットはWordまたはHTMLならOK。PDFは必須ではない。
  • ドキュメント中に画像はそれなりにある。スクリーンキャプチャ、構成図みたいなダイアグラムもある。
  • ドキュメント作成者のメインPCはWindows。
  • ドキュメント作成者はプログラマやインフラ担当などの技術者で、コンピュータリテラシーは高い。

Word

知らない人はほとんどいないであろう、Microsoft社のWord。

Wordの良い点:
  • 初心者にもとっつきやすく書きやすいUI。
  • 日本語の文法チェック機能、文章校正の機能がある。
  • ツールを切り替えることなく文章中に図を作成することができる。
Wordの残念な点:
  • プレインテキストではないのでGitなどのバージョン管理ツールとの相性が悪い。
  • 採番機能はあるがよくずれるため当てにならない。
  • 1ファイルに大量に記述すると、良く落ちるようになったり開けなくなったりする。これは回避方法として、章単位にファイルを分割するといった方法がある。というか、分割しないと複数人で作業しづらいので、分割はした方が良い。分割したファイルから目次を生成する機能がWordにはあるのでこちらを使おう。
  • 自由に書き易い分、スタイルの統一が大変。特に複数人で1つのドキュメントを作成する場合。スタイル機能をちゃんと使いこなす必要が出てくるのだが、難易度がグンと上がる。
  • たとえスタイル機能を使っても、スタイルの適用をミスっていたりすると目視で確認するのが大変(よ〜く見ないと分からないとか)。前の仕事では、スタイルのミスを見つけるために人力でひたすらマニュアルのスタイルチェックを行っていました。画面では確認しにくいため印刷してチェックするとか、紙の無駄遣いにもなっていた。
  • その他、デフォルト設定だと使いづらく色々とカスタマイズした方が良い(標準だとおせっかいすぎるので)。以下の本を見て使いこなすのがおすすめだが、これを全利用者に個別に設定してもらうのも一苦労。

エンジニアのためのWord再入門講座 美しくメンテナンス性の高い開発ドキュメントの作り方

エンジニアのためのWord再入門講座 美しくメンテナンス性の高い開発ドキュメントの作り方

DocBook

DocBookは技術文書のためのマークアップ言語で、XMLでドキュメントを作成していきます。XMLからHTML、PDF、manページ、HTMLヘルプなどを生成することができる。
DocBookについては2008-2009年頃に使用していたことがあり、ブログにも書いていた。当時はEclipseのXMLエディタでドキュメントを書いていたが、XMLスキーマを読んで検証もしてくれるし、補完もOKで、バージョン管理ツールも統合されているので便利だった。

DocBookの良い点:
  • プレインテキストで記述できるためGitなどのバージョン管理ツールと相性が良い。
  • プレインテキストなので軽量。サクサク書ける。
  • DocBook用のXMLスキーマが定義されているので、スキーマを読み込めば構造の検証も生成前に事前に行える。単純なタグの記述ミスも事前に防げる。
  • XMLエディタを使えば、XMLスキーマを読み込んでXMLタグの補完も可能。
DocBookの残念な点:
  • XMLなのでどうしても記述が冗長になりがち。特にリストとか表とか。コンピュータには優しいが人間には余り優しくない。
  • 図は画像ファイルとして管理する必要がある。Wordのようにシームレスに扱えない。また、JPGとかPNGで管理しちゃうと、オブジェクトのレイヤー情報が失われてちょっと位置をずらすとかの修正も大変。Visioなど別ツールのファイルでオリジナルを管理する必要が出てくる。
  • 出力フォーマットのスタイルカスタマイズが大変。DocBookではXSLTでXML->HTMLに変換しているのだが、XSLTが難解すぎる。
  • ドキュメント生成環境を構築するのに一苦労(今だと改善されている？)
  • 日本語のPDF作成に難あり(今だと改善されている？)

Sphinx

Python製のドキュメント生成ツールです。DocBookとは異なり、XMLではなくreST(reStructuredText)記法でドキュメントを作成します。DocBookと同じように、1つのソースからHTML、PDF、ePubなどを生成することができる。

Sphinxの良い点:
  • プレインテキストで記述できるためGitなどのバージョン管理ツールと相性が良い。
  • プレインテキストなので軽量。サクサク書ける。
  • XMLではなくreST(reStructuredText)記法なので人間にも優しい。やはりXMLと比べると断然こちらの方が見やすさは上。
  • 環境構築も比較的容易。
  • 出力したHTML単体で、全文検索機能を提供するなど他のツールにはないオマケ機能もある。
Sphinxの残念な点:
  • ツールによる構文の事前チェックやreST記法の補完などのサポートが余りない。vimとかemacsならハイライト機能などあるが、ドキュメント書く人はWindowsユーザが大半なので難しい(ただし、reST記法はそこまで難しくないので補完は無くてもほとんど困らなさそう)。
  • DocBookと同じで、図は画像ファイルとして管理する必要がある。Sphinxにはblockdiagのようにテキストからダイアグラムを生成する機能も使えるけど、スクリーンキャプチャとかダイアグラムで表現できないケースは多い。

ReVIEW

Ruby製のドキュメント生成ツール。名前がSEO的に微妙でググってもヒットし辛いのが難点。参考サイトへのリンクを記載しておきます。

こちらもSphinxと同様に、XMLではなくWiki に似た簡易フォーマットでドキュメントを記述していく。出力も同様に、HTML、PDF、ePubなどに対応。

ReVIEWの良い点:
  • プレインテキストで記述できるためGitなどのバージョン管理ツールと相性が良い。
  • プレインテキストなので軽量。サクサク書ける。
  • XMLではなくWikiっぽい記法なので人間にも優しい。
  • 秀丸での編集支援マクロがありWindowsユーザでも書きやすそう。
  • 環境構築も比較的容易。
ReVIEWの残念な点:
  • DocBook、Sphinxと同じで、図は画像ファイルとして管理する必要がある。
  • 出版を目的にして開発されたためか、HTML出力機能は弱い。インデックスのページがなかったり、デフォルトのスタイルもない。ただし、スタイルはないが出力されるHTMLはシンプルできれいなので、CSSだけ作成すればスタイルのカスタマイズは容易と思われる。

結論

結論としては、今回はSphinxを選択する予定。

理由
  • Wordはバージョン管理との相性が最悪なのが一番痛い。あと、スタイルを統一するという点にすごいパワーがかかる(前の仕事で身を持って経験済み)ので外した。
  • 製品エディションでマニュアル構成が変わるのだが、共通部分は二重管理したくない。Wordだと動的な構成に対応するのは厳しい。ここはDocBook、Sphinx、ReVIEWであればプログラムで操作できるので対応しやすいはず。
  • DocBookは個人的にはなれているのだが、技術者がドキュメントを書くとはいえ、今後継続的にメンテナンスして行くことを考えると、人に優しいWiki的な記法が望ましい。
  • ReVIEWも記法としてはシンプルで魅力的だが、出力フォーマットが出版メインでHTMLだと現時点では貧弱。

正直なところ、Sphinx、ReVIEWの2つは全然使いこんでいないので、今後落とし穴にハマる可能性はあるが、新しいことにチャレンジするのも大切なのでいい機会と思って頑張ってみます。

おまけ

自分達で使うケース前提だが比較表も作ってみた。

é …ç›® Word DocBook Sphinx Review
エディタのUI*1 ◯ △ × △
作図サポート ◯ × △ △
読み易さ ◯ △ ◯ ◯
バージョン管理との相性 × ◯ ◯ ◯
日本語校正 ◯ × × ×
環境構築が容易か ◯ × ◯ ◯
章、節番号などの採番 △ ◯ ◯ ◯
スタイルの統一が容易か × ◯ ◯ ◯
スタイルのカスタマイズが可能か ◯ △ ◯ ◯
HTML出力 - ◯ ◯ △

*1:Sphinx、ReVIEWはWindows上の秀丸などのテキストエディタを想定。DocBookはXMLエディタを想定。