業務システムのドキュメントは誰のために書くか
これはすごい。よくここまで言葉で説明しきったなあ。
・ ドキュメントを作る目的は、書くことでも読むことでもない。レビューすることを通じて、互いの理解の差を埋めることが目的である。
・ ドキュメントに必要な内容はチームの成熟度、メンバーのスキルによって異なる。
・ ドキュメントを作るというのはプロジェクトの文化を作ることの一面であり、ドキュメント作成というツールを使って、文化やスキルレベルの違う後続のチームメンバーをトレーニングしていく活動である。（その意味ではスキルが上位の人もトレーニングの対象となる。）
ものすごく同意する。これまでのドキュメント必要／不要の２項対立から一歩進んだ考え方。
業務システムの開発の中で、ドキュメントほど一般的な問題でありながら適切な解が出ていないものはないと思うのだけど、他の人たちはどんな風に考えながら、どういうドキュメントを書いているのかなぁ。
よく言われるのが、基本設計書は「５年後の誰か」を想定して書くという考え方。大規模な業務システムってサグラダ・ファミリア教会の建築みたいなところがあって、当初の設計者や開発者はすっかり世代交代して、もはや誰もいないのに実運用と修正開発はずっと続いているようなことは普通によくある。それで何年か経ったある日問題がおきる。それはずっと潜伏していたバグが顕在化しただけかもしれないし、当初は想定していなかった税率改正や電子マネーの登場に対応できなかったのかもしれない。そのときコードを修正する未来の開発者にどうしても伝えたいことをダイイングメッセージ（？）としていま書き残しておくのが基本設計書。
まあここまではわりとみんなに理解されている話だと思う。
最近なんか風当たりが強いなあと思うのは詳細設計書。会社によっては内部設計書とかプログラム設計書と呼んでたりするアレね。プログラムの１行に対して日本語１行書いてたりして、何の意味があるんだってDISられているわけですが。ああ見えて使い方によっては役に立つと思うんですよ彼も。
僕の思う詳細設計書は、コーディング作業を加速するためのものであり、消費するためのドキュメント。つまりそれがあることによってコーディング終了までの時間が短縮されるなら書いたほうが良いってこと。それでコーディングが終わったら、もう忘れちゃっていい。捨てちゃってもいい。だってどうせ後から見たりしないから。
最近の進化したプログラミング言語に慣れていると想像しづらいかもしれないけど、CやらCOBOLやらで書かれたソースって本当に読みづらい。しかもO/Rマッパーなにそれ？ みたいなSQLを埋め込んで条件が20個くらいつながったWHERE句があったりすると自分で書いてる最中でもなにやってるんだか分からなくなる。これは昔話をしているんじゃない、昔開発された現役システムの修正開発では今でもよくあること。
だからコードを書く前にワンクッション置いて可読性の高い自然言語でプログラムの下書きというかデッサンみたいな感じでロジックを書き起こすと、結果的にコーディング終了までの時間が短縮される。
・ ドキュメントを書くことと人に説明すること、フィードバックを受けることはワンセット。
とあったけど、この場合自分の頭をすっきりさせるために（自分に説明するために）書くという感じかな。
まあ、旧式の言語や旧式のアーキテクチャに引きずられたバッドノウハウであるとは思うので、何年か経って業務システムの開発環境がすっかり変わったりテスト駆動開発が浸透したりしたら、そのときは本当に詳細設計書に引退してもらいたいとは思うけどね。
まとめると、基本設計書は５年後の誰かのために書き残す、詳細設計書は自分のために書き捨てる、ってことで。
