仕様書をTracのWikiに記載する

「仕様書をSubversionとTracで管理する」に続いて、今回は仕様書をTracのWikiで作成する話。

Tracの登場以前に、仕様をPukiwikiで書き始めたのがそもそも発端だけど、Wikiを使うメリットとして下記が挙げられると思う。

仕様同士のリンク
経験的に言って、仕様書は一つだけでは収まらないことが多い。関連する仕様として、仕方なくたくさんのファイルを作っていく事になるのだけど、数が増えると相互参照が大変な作業になる。この点、WikiならWebのリンクを辿るだけなので、情報へのアクセスが容易だ。
仕様の一意性確保
（社内サーバにて）一意のURLと仕様が紐づけられるので、仕様として意味するところを明確に指定できる。ファイルだとファイル名に整理用の数字を入れたり、最新版の資料の置き場所を常に意識しておく必要があった。
ファイルよりも更新が簡単
気分的なものが大きいかも知れないけど、ファイルを開いて該当箇所を探し出して更新するよりも、Web画面で更新した方が手っ取り早く作業できる気がする。

その後、「Wikiを使った情報管理」で書いたようにPukiwikiからTracへ乗り換えた。Pukiwikiに比べて、TracのWikiを使う場合のメリットは下記の通り。

チケットへのリンク
仕様変更の原因となった障害や要求項目に対するチケットへのリンクを記載しておくと、後で他の人が見ても変更理由を容易に理解できる。さらに、チケットへのコメントとして、該当する仕様のWikiページ名を書いておけば相互にリンクされるので、より分かりやすい形になる。
ソースコードリポジトリへのリンク
数十万行のコードがリポジトリに入っていると「そもそもこの仕様はどのソースコードに実装されているのか？」ということすら簡単には分からなかったりする。その点、Subversion リポジトリへのリンクが記載されていれば、仕様とソースを突き合わせて簡単に確認出来る。
変更履歴の保存
商用製品としてソフトウェアを出す以上、仕様変更の履歴は全て確実に保存しておく必要がある。誰がどのような理由で仕様を変更し、どんなソースコード変更に結びついたのか、トレーサビリティ確保の記録用としてTracのWikiは有効だ。

今までOffice等のソフトを使って仕様書を作っていた開発者は作業方法が少々変わるので戸惑うけど、「仕様書」「ソースコード」「チケット（障害、タスク）」間のトレーサビリティが確実に確保できるメリットは大きいと思っている。

その他、ささやかなTipsはこんなところ。

管理者による整理
誰でもWikiを書けると、ページが乱造され無法地帯となりかねないので注意が必要。特に、tracのWikiはページ名を後で変更できないのでページ（パス）構成は統一するように誰か専任の管理者が欲しい。また、各ページの構成や体裁を合わせるためにページのテンプレート*1を事前に作って用意しておくと良い。
仕様書提出はPDF
開発グループの外へ資料を出したり、承認作業が必要な場合には、WebページをPDF化して提出している。変更履歴が必要な場合も、Wikiの画面で履歴が取れるので、そのままPDFに添付する。履歴には「いつ、誰がどのような変更を行ったのか？」という情報が載っており、これだけの情報を出せば文句はあるまい。（Webページそのままなので見た目が今ひとつという指摘はあるけれど、体裁よりも内容重視という方針で押し切っている）

Excelのように表にまとめるべき仕様を書くのは苦手だし、いろいろ制約があるのは事実だけど、利用範囲を選べば結構便利に使えると思う。以上、ご参考までに。