ドキュメントを書きましょう

私が最初に入社した会社は親会社が策定したドキュメントフォーマットがきちんと整っていて、何をどこにどれだけのものを書けばよいか、規模によってどれを客先に納品するかなど決まっていました。
そんな会社で育ったせいか、ドキュメントというのはとても重要だと、その会社を辞めた後でも思っています。

それがいつからでしょう。
システムも「うまい、早い、安い」でないと仕事が取れなくなって、受注価格を下げるようになって、工数削減で何を犠牲にするかで「ドキュメント」をきっちり書かなくなることが多くなったように思います。

「どうせ詳細設計なんか書いても、お客さんが見てもわからないから」
「コード書いたほうが早い」
「工程が進むうちに設計書と実装がどんどんかけ離れていって、メンテナンスするのが困難だから」

そんな声をよく聞きます。

1.はそれでもよいと思います。
なぜなら、設計書は家を建てるところでいう所の「図面」だと思うのです。
図面はお客さんよりもそれを見て大工さんが作れなければ意味がないです。
図面を引かない家に住みたいですか？そういう話だと思います。

2.はわかるような気がします。
決定した仕様を技術者の言葉に翻訳するのが設計書、コンピュータの言葉に翻訳するのがコード。
同じことを、二つの言葉に、しかも同期をとって翻訳しなければならないのです。
面倒ですね。コードだけなら一つでいいですね。
でも、例えば「このアプリケーションはどんな処理をやっているのか」の概要を知るために「コードを見てください」ってのはどうでしょう。
それが納品した客先だったり、保守運用の会社だったりすると「コードを見ろ」はお粗末ですね。
そこで「そこそこの設計書」をどこでも書くと思います。

でもそれが3.の「設計書と実装の乖離」につながり、同期をとろうと思えば「メンテナンスする」というコスト高の原因になってくるのだと思います。

さて、ここまで問題は出しても解決策を書いてきませんでした。
というか、自分が言いたい解決策は表題通り「ドキュメントは書きましょう」ということなんですけどね。
そこはコストとして削れるところではない、と主張したいわけです。

もう一度書きます。
「図面を引かない家に、あなたは住みたいですか？」

ドキュメントのメンテナンスを効率よくするための解決策、一緒に考えましょう。
DOAとか、なんとか、かんとか。