前置き
長年、書いてはバインダに挟まれキャビネットの奥深くにしまわれるシステム仕様書を書いてきました。
単にハンコをつくための台紙にしかならない仕様書作成ほど、エンジニアのやる気を削ぐものはありません。だからこの業界では、仕様書不要論なんてあったりするんですよね。
でも、それは間違いです。不要なのは仕様書ではなく、使われない仕様書です。
使われる仕様書を書いてみんなで幸せになりましょう。
まず読む
やさしい機能仕様 - Joel on Software
http://japanese.joelonsoftware.com/Articles/PainlessFunctionalSpecifi-2.html
読んだ？
大丈夫。長いけれど面白いのでするする読めます。
この知識が一番ベースになります。
で、読んだ？
はい。
読んだあなたには、仕様書が必要だということ、どのような仕様書を書けばそれが不要なものにならないのか、既に悟りの境地にすらあると思います。
そこに蛇足感満載ですが、いくつか私の経験の中から付け加えてみます。
複数ドキュメント間の重複記述は絶対に避ける
仕様書を腐らせる一番大きな原因はなにか？それは更新の手間です。
更新がめんどくさくなると、コードだけ修正してドキュメントを修正しない、なんてことが起き始めます。
そしてコードとの乖離がほんの5%程度になった時、そのドキュメントはもう信用ならないものになると感じます。
なぜならウソが書いてあるからです。
しかもどこがウソなのかわかりません。もう正解をさぐるにはコードを見るしかなくなります。
ここに仕様書の価値がゼロどころかマイナスになりました。
こういった悲しい結末を避けるためには、変更箇所を局所化することが第一歩です。
少なくともドキュメントの変更は一箇所で済みます。
機能仕様と技術仕様は厳密に分離する
「やさしい機能仕様」を読んだあなたは既にご存知だと思いますが、それぞれの役割は以下です。
なぜ分けなければならないのか？それは対象読者が異なるからです。
機能仕様は、顧客やプロデューサーなどの非エンジニアであり、技術仕様は、ともにコードと格闘するエンジニア仲間向けです。
読む人のことを考えれば、読むべきドキュメントの量は減らすべきです。読まれないドキュメントは悲劇の存在です。
読まれるために、ここは厳しく厳密にいきましょう。
技術仕様はソースのヘッダに書く
仕様書のゴミに変えてしまう更新の手間を減らすために、なるべくドキュメントはコードの近くに置いておくべきです。
物理的な近さが、片方しか更新されないという悲劇を防ぎます。
Markdownが使えれば、体裁もかなり整えられます。
apigen等良いドキュメント化ツールもあることですし、対象読者はエンジニアですし、むしろその方がテンションもあがろうというものです。
明日からレッツトライ！
さ、テスト仕様書かかなきゃ....