« Google に ウィルス感染を疑われちゃった・・・。 | メイン | python で cgi »

仕様書は Excel か Word か他の何かか

みなさん、仕様書は何で書かれてますか?

アルファルファモザイクより「仕様書をExcelで書くんじゃねぇ」
はてなブックマーク - アルファルファモザイクより「仕様書をExcelで書くんじゃねぇ」

私の会社では、仕様書のテンプレートがExcelとWord形式で管理部門から提供されているのですが、利用されているのはExcelが多いようです。

個人的に思う仕様書として重要な要素は、まず「書かれている内容」、次に「意味・意図が適切に伝わるかどうか」、そして「メンテナンス・運用のしやすさ」かなぁ。

これが守れていれば、何で書かれていたって良いと思います。

何を選択するかは、当然、システムの規模や内容にもよってくるわけで。

数名で作り上げ、運用もそのメンバーでやるシステムなら、仕様書は手書きで、重要事項はWikiへという運用でも大丈夫でしょうし、数百名が関わるような大規模PJでは、電子データで運用しなければ情報がうまく伝わらないでしょうし。

一番ナンセンスなのは、「いつもそうだから」という理由で、何も検討せずにフォーマットを決めてしまうことかなと思います。

Word と Excel どちらで書いてもそれほど変わらないと言う場合は、僕はWordを選択するかなぁ。
印刷のときに変な気遣いをしなくて良いというところが好きです(とはいえ、たまに貼り付けているオブジェクトがバグることがありますけど)。

ドキュメントがメンテナンスしづらいと、ドキュメントと画面の乖離がどんどん進んでいくので、Web系のシステムならいっそ画面に書き出したら良いんじゃないかと思い↓こういうのも作ったことあります。

showyou --- HTML に Ajax でドキュメントを出力 (でぃべろっぱーず・さいど)
showyou-0.0.2 Release (でぃべろっぱーず・さいど)


最終的に一番頼りになるドキュメントはソースコードだと思うので、ひたすらテクニックに走るだけじゃなく、後から見て分かりやすく、誤解を生まないようなロジックやコメントを書いて欲しいです。

↓笑い話として、こんなソースコードの例が良く挙げられますよね。

// hoge が 5 より大きいとき処理する。
if ( hoge < 5) {
hoge += 10;
}

コメント (1)

Gates:

ちょくちょくファイルが壊れるWordで
重要な仕様書を書く人間はマゾだとおもう。