マニュアルは何が良いか

その他

同じようにユーザ向けのマニュアルについても。設計ドキュメントとは異なって外部向けとなるのが大きなところ。

  • 複数人で編集することが多い
  • マニュアルが複数冊で構成されているとき共通の部分が結構ある
  • 外部向けなので体裁が整っている必要がある
    • スタイル、用語の統一などなど
  • プロダクトによっては、国際化対応が必要

個人的には、オープンソース系で良く使用されているDocBookがいいんじゃないかと思ってたまに使ってきました。DocBookではXMLで文章を書いておき、そこからXSLTでHTML、PDF、Eclipseヘルプ形式などに変換することができます。XMLなので中身は単純なテキストであり、構成管理ツールとも親和性が良いです。国際化も、多くのオープンソースプロジェクトで実施されているという実績があります。ここらへん、まだまだ勉強不足なので今後調べて行きたいと思う。
DocBookの難点は、最終的な成果物であるHTML、PDFに変換できるようになるまで環境を整備するのが非常に大変なところ。書くのはXMLだけどよく使うタグはそんなにないのですぐに慣れるのであんまり問題ではない。EclipseなどのXMLエディタなどで簡単に書けます。特に辛いのがPDFへの変換。見栄えの良いものがなかなか容易に作れないのが現状。ここは現状、商用ツールに頼った方が良いのかもしれない。。。

DocBook以外には、IBMがオープンにしたDITAというのもあります。こちらも気になるところ。