ソフトウェアのマニュアル管理に適したツールは何が良いのでしょう。アリエルは色々と迷走しています。

要求は以下のとおりです。

1. (オンラインマニュアルにも使えるように)HTMLで出力できること
2. 印刷して見たい人も多いので、その要求に答えられること(それなりの見栄えのデザインにできること。PDF変換機能など)
3. 非プログラマの人が保守できること
4. しかし、プログラマも参照できていじれる方が望ましい

候補としては次のものがあると思います。

• docbook
• その他XML
• 非XMLのフォーマット(rst, yaml?)
• HTML直書き
• CMS系ツール
• Microsoftワードフォーマット
• wiki

docbook はオープンソース系ではデファクト標準で、GIMPやApacheのマニュアルでも使っています。要求の1と2と4は満たしていますが、3がちょっと危ないです。個人的にはdocbookは好きでも嫌いでもありません。

OpenOfficeのマニュアルは拡張子xhpのXMLフォーマットで保守しています。http://svn.services.openoffice.org/ooo/trunk/helpcontent2/source/text/swriter/ これらのファイルを手書き(?)しているのが信じられません。docbookの方が耐えられます。

非XMLの他フォーマットは何を選ぶかが大きな賭です。世間でのツールの充実を考えると、XMLに軍配があがりそうです。ありえるえりあはrst(restructuted text)を使っていますが、経験上、まったく薦められません。

HTML直書きは平凡ですが、下手にXMLを書いていると、結局、XHTMLでいいのではないか、という気になってきます。実は AirOneのオンラインマニュアル はHTML直書きです。結論としては、要求の1と3は満たして、4が微妙、2が満たせず、という感じです。個人的には、デザインを綺麗に適用済みのHTMLはいじるのに勇気がいります(触ると壊れそうなので)。文書構造だけ持つXMLの方がいじる敷居は低いです。

CMS系ツールは選択肢として悪くありません。要求の1と3と4を満たせます。2はツールに依ります。 AirOneのFAQ は昔phpMyFAQのシステムでしたが、今はMT(Movable Type)になっています。MTの難点は(企業で使う場合)有償ということです。デザインが安っぽくなりがちなのでマニュアル感を出すには工数が必要です(FAQはマニュアル感を捨てています)。HTML直書きと同じように2の問題があります(たぶん。MTにpdf出力があるか知りません)。

社内では Forrest をマニュアルに使っています。CMS系ツールとは言え、MTのようにブログっぽくはなく、XML直書きで保守します。要求の1と2と4は満たせますが、3が微妙です。そんなに難しくないXMLなのですが、何かと不評です。OpenOfficeのxhpファイルを見ると評価が変わるかもしれません。

実はForrestを使う前はMicrosoftワードフォーマットでした。要求の2と3は満たせますが、1と4を満たせません。OpenOfficeで編集できるとは言え、プログラマの拒否反応が大きすぎて使えません。

wikiは要求の1と4を満たしますが、2と3が微妙です。ブログとさして変わらない難易度だと思うのですが、wikiは難しい、という印象があるようです。

世間的にはマニュアル管理はどうしているのでしょう。