topicタイプのバランスで，最強の仕様書を目指す…目指せるはず．たぶん
最近，とある会社に対して技術支援している．ホワイトボードに手書きした説明が，想像以上に議論の叩き台として有効だったので日記でシェアしておく．
DITAを知らない人のために，超入門．
DITAは，IBMが最初に始めた仕様書のフォーマットでXMLで…なんてのはIBM dW辺りを読んで頂けばよろしいかと．
DITAの慧眼は，仕様書のコンテンツを，task/concept/reference/glossaryという限られたフォーマット*1を基にする文書の細切れで蓄積し，必要に応じて仕様書として纏めればよいという見切りの良さにある．このフォーマットをDITAの世界ではtopicという．
物理的なものを示されないと理解できないひとは，京大式メモとか，システム手帳のリフィルとかを想像してもらえばかなり近い．
TeX，Docbook，各種ワープロがbook単位での記述を暗黙的に仮定していたことをおそらく教訓にしているのだろうと思う．これらのドキュメントプロセッサのフォーマットは，使う側がハッキリと意図しないと再利用性に今ひとつ難が出る．
topicタイプで問題点を炙りだす．
さて，実例…じゃなかった作り話をひとつ．
零細ソフトウェアハウスA社が社内で使っていた組込みライブラリfoobarがある．foobarは画期的なユーザエクスペリエンスを提供できた．foobarを組み込んだ製品がちょっとしたヒットを飛ばしたのは想像に難く無い．
ある日，顧客B社がfoobarを自社製品に組み込むため，コンポーネントとして提供して欲しいと言い出した．A社はマシな会社で，仕様書は用意していた．A社は別件があってB社にべったりつきあえない．要求を飲んで，仕様書を含む一式を提供した．
しかし，数ヶ月経ったある日，顧客から仕様書の内容が薄いとクレームがついた．何故だか判らない．A社から見れば社内で仕様書絡みで困ったことはない．質問が山のようにくる．対応しようにも，そもそも相手が何をいっているのか解らない．顧客の理解レベルが低すぎるのか?
おそらく世の中に溢れすぎているようなストーリーだろう．溢れすぎているため，日記でシェアしても，このA社やB社がどこなのか，全く推察できないに違いない．(なんて不幸なことだ!)
こんな不幸な場合の分析手段として，DITAのtopicは割と便利に使えるっぽい．
ソフトウェア会社の社内ライブラリにおいて，仕様書とは大抵API仕様書やデータ構造仕様書のことを指す．これは，DITAのtopicでいうところの，reference に相当する．この類の仕様書は，よほど管理が悪い会社でなければ，何らか存在するし，でっち上げもできる．JavaDocやHotDoc(古い?)辺りで自動作成ができる類のものだから．
少なからずのソフトウェア会社は，このレベルで仕様書があると看做し，外販し，痛い目を見る．
何故なのか．DITAの思想が正しければ，理由は簡単．
仕様書はreferenceのみで完結せず，task/concept/glossary という他の要素も提供されるべきである．ただし，どのトピックをどれだけ配分べきかというのは，仕様書を参照する者の性質やらコストやら色々な拘束条件によって決まる．
おそらく最も軽視され，最もコスト上昇の原因になり易いのはglossary．用語の拠り所が弱いと，双方がオレオレ定義の言葉を使い始め，延々とボールの投げ合いが続く．この国では人件費が一番高いので，コミュニケーションコストは真っ先に殲滅すべき対象の筈．
割と必要性は意識されるものの，省かれ易いのは，task．「サンプルソースコードをas isで提供します」で逃げがちだけれども，相手環境ではサンプルコードのビルドができなくて炎上したりする．ペリフェラルのマニュアルに載っている，いかにもハードウェア技術者が投げやりに作ったサンプルコードとか，組込み技術者なら一度は怒髪天な経験があるはず*2．自然言語の不完全性はあるにせよ，自然言語も併用すべき．
モヒカンエンジニアは不要だと切り捨て，そうでない人は必要性を感じるものの，誰も書けなくなるケースが多いのが，concept．本質的には，作った人にしか書けない．技術的想像力にやたらと長けた人や，作った人並みに技術をモノにしているエバンジェリストに恵まれれば解決可能かもしれない．しかし現実の典型は，原作者がマッチョなモヒカンで…とか，原作者は退職しました…，だろう．だから，意識して書く/書かせる習慣を組織に持たせる必要がある．
なぜこのような実装になったのか，という情報は，プログラミングでドツボにハマる可能性を下げる効果がある．逆説的にconteptが解っていないと，ドツボにハマり易い．大抵の場合，怒りの矛先は，知らなかった自分ではなく，知らせてくれなかった仕様書に向かう．
話をA社に戻す．もう想像がつくと思うけれど，A社が持っていたのはAPI仕様書．零細なので，設計の意図や使い方を共有するコストはA社にとっては低く，foobarを外に出さなければ文書化する必要性が無い．
しかし，API仕様書は，DITAのtopicにマッピングすると，referenceの塊でしかない．B社が理解できずオレオレ定義の言葉を乱発するのは，DITAの世界を見た後ならば，容易に想像がつく．
メトリクスとしてのDITAの可能性
てなわけで，DITAのtopicを信じてみて仕様書を分析してみると，仕様書に何が不足しているのかが割と簡単に炙りだせる．炙りだしたあと，どう対策するのかは，仕様書の管理者の仕事だ．極端な話，referenceしかない仕様書でも，API仕様書としては成立している可能性がある．それで十分かどうかは，一般論としては何とも言えない．
DITAで書くことは，必ずしも必要ではない．思想のエッセンスを引っ張ってくるだけなら，MS wordで書かれた仕様書にだって適用できる．印刷した仕様書に4色ボールペンで色分けしてみるとかなら，導入コストは殆どかからない．
理想的には，DITAで書くと良いと思う．XMLで書かれていて，1 topic - 1 file ．メトリクスを出し易いはずではある．
…お前のところはどうなのかって? いえまだまだ不十分ですすんまそん．
蛇足．
…なのだけれど，日本でDITAというと，XMLエディタに何を使うのかとか，どのコンテンツデータベースを選ぶべきかとか，ツール屋さんにお金を落とす方法にしか話が行かないよね．なんでだろ．ドキュメントに品質評価の考え方が根付いていないとも思えないのだけれど．
