2008年4月16日
最近のお題はプログラム設計書らしいので釣られてみる
おごちゃんの雑文の「プログラム設計書」って必要？って意見にほぼ全面的に同意 
全面的に同意してるので、新たに書くこともないのだが…
はっきり言って、うんこ文書を生産して満足している奴らが多すぎる。まぁ、わたしも書かされるわけだが 
で、なんでこんな意味のないモノを書くの 
って聞くとじゃ書かなければ誰がメンテナンスするんですか とか、どうやってコミュニケーション(設計と実装間)するんですか と質問返しにあう
個人的には、ドキュメント読まなけりゃメンテナンスできないコードを書いてる時点で負けだし、ドキュメントをいくら書いてもコミュニケーションギャップは埋まらないと思ってる。
いや、逆にドキュメントを書きすぎることでギャップを広げてさえいるように感じてる。
でも、こういう考えな人にいくら言っても平行線なことが多い 
稀に通じる程度。
コードは非常に正直なので、問題があればリリース前に必ず最新の状態に保たれる(まぁ、構成管理ミスとかはこの際無視)。でも、ドキュメントやコメントは不正直なのでたいていは最新の状態に保たれない。
もちろん、最新の状態にドキュメントを保つ人も中には居るが…問題は一人でも保たない人が居るとドキュメントの信頼性が地に堕ちること 
別にドキュメントを全く書かなくて良いとか、クヌース御大のように文芸的にとも言わない。でも、コードの変更にイチイチ引っ張られるようなドキュメントは絶対に書くべきではないし、そんなドキュメントは要らない。
さらに、この「なんとか仕様書」とか「なんとか設計書」ってのは結構、会社や会社内の組織、さらにはプロジェクトでも記述レベルは当然として様式まで違ったりする。まぁ、客先指定の場合もあるので…その場合はどうしょうもないけど
なので、わたしは仕様書を書く代わりに「取り扱い説明書」を基本的に書くことにしている。内部的には、「取り扱い説明書＋α」で、これがドキュメント 
取り扱い説明書は、客先に絶対提出されるモノなので、コードの次に正直なことが多いのも大きなメリット
「＋α」の部分が何かと言うと客先に見せられない部分 
他のドキュメントは一切書かない。
取り扱い説明書って、文体さえ変えれば立派な仕様書だし、設計書だと思うんだけどなぁ 
なのに最後に書かれることが多かったり、まったくシステムをわかってない人が書くことが多いんだよなぁ 当然、テクニカルライターなんて本職は居ないし
そんなドキュメントとして魅力的な取り扱い説明書なのに虐げられてるんだよな…。
一理ある
このブログで関連すると思われる他の投稿
TrackBack URL :
