Personal tools
You are here: Home ブログ 井上 ソフトウェアのマニュアル管理に適したツール?
« December 2010 »
Su Mo Tu We Th Fr Sa
      1 2 3 4
5 6 7 8 9 10 11
12 13 14 15 16 17 18
19 20 21 22 23 24 25
26 27 28 29 30 31  
Recent entries
Apache2.4のリリース予定は来年(2011年)初め(あくまで予定) inoue 2010-12-23
Herokuの発音 inoue 2010-12-20
雑誌記事「ソフトウェア・テストPRESS Vol.9」の原稿公開 inoue 2010-12-18
IPA未踏のニュース inoue 2010-12-15
労基法とチキンゲーム inoue 2010-12-06
フロントエンドエンジニア inoue 2010-12-03
ASCII.technologies誌にMapReduceの記事を書きました inoue 2010-11-25
技術評論社パーフェクトシリーズ絶賛発売中 inoue 2010-11-24
雑誌連載「Emacsのトラノマキ」の原稿(part8)公開 inoue 2010-11-22
RESTの当惑 inoue 2010-11-22
「プログラマのためのUXチートシート」を作りました inoue 2010-11-19
「ビューティフルコード」を読みました inoue 2010-11-16
Categories
カテゴリなし
 
Document Actions

ソフトウェアのマニュアル管理に適したツール?

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

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

  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は難しい、という印象があるようです。

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

The URL to Trackback this entry is:
http://dev.ariel-networks.com/Members/inoue/software-manual/tbping

Re:ソフトウェアのマニュアル管理に適したツール?

Posted by Anonymous User at 2009-04-19 19:58
AsciiDoc はいかがでしょう?
うちも検討中(私が勝手に、、、)。

Re:ソフトウェアのマニュアル管理に適したツール?

Posted by inoue at 2009-04-21 02:12
個人的には、テキストでリストや表を書ける表記は好きなのですが(WYSIWYG不要派)、世間的には不評のようです。XMLは、XMLだから、という理由で受け入れられることがあります。XMLは痛みを忘れる魔法の言葉です。

Re:ソフトウェアのマニュアル管理に適したツール?

Posted by Anonymous User at 2009-04-26 13:32
WikiならエンジンにMediaWikiというのはどうですか?Wikipediaのエンジンですから書式も馴染んでいる人は多いでしょうし、PDF出力の拡張もあった気がします。それにしてもSunの絡んでいるプロジェクトってやたら無駄に複雑なテクノロジを導入しているような気が。

Re:ソフトウェアのマニュアル管理に適したツール?

Posted by fchiba at 2010-01-07 14:23
古い話題へのコメントで恐縮です。

同じような問題で悩んでいます。
> rst(restructuted text)を使っていますが、経験上、まったく薦められません。
とありますが、どのような点が問題となったのか教えていただけないでしょうか?

Re:ソフトウェアのマニュアル管理に適したツール?

Posted by inoue at 2010-01-07 23:29
少し誤解を招く表現でした。ここでの「経験」は、「運用した経験」ではなく「個人的に使った経験」の意味です。
薦められない理由は、表現力が特に強力でもない割に文法が厳格でエラー遭遇率が高い点です。

Re:ソフトウェアのマニュアル管理に適したツール?

Posted by fchiba at 2010-01-08 11:57
なるほど、文法そのものに問題あり、ということですね。
参考になります。ありがとうございました。

ちなみに、弊社の現状はワードですが、CMSに切り替えようと画策中です。(印刷はブラウザからAcrobatでPDF出力)
CMSがrst使ってると同じ問題が発生してしまいますね…
Add comment

You can add a comment by filling out the form below. Plain text formatting.

(Required)
(Required)
(Required)
This helps us prevent automated spamming.
Captcha Image


Copyright(C) 2001 - 2006 Ariel Networks, Inc. All rights reserved.