ドキュメントのイロハ
今常々考えていること。どうやったら最小限の労力で分かりやすいドキュメント*1を作れるか？
例えば詳細設計書を作成する目的として、以下のような状況が想定され得る。
ツールを使ったドキュメント作成技法（前編） − ＠IT
- 詳細設計書を基に実際の開発を行う
- 納品成果物に含まれているために必要（実際の開発ではそれほど参照されない）
- 運用・保守向けに必要
1番目の目的について。プログラムを組むための設計書なら、そこに書くことを規定することは結構簡単。極論、ソースコードに記述するものを一語一句書けばいいだけだし。それが、果たして時間を費やしてまで取り組むべきものかは別問題としてね*2。
2番目は本質的でないので、とりあえず置いておいてｗ
3番目の目的のための設計書。これがよく分からない。まだ本格的な運用・保守の経験がないからだろうけど、どういったものがあると運用・保守担当者が嬉しいのかがいまいち見えません。一律で書くことを規定できるものでもないだろうし。
このうち、「詳細設計書を基に実際の開発を行う」のであれば、その設計書の内容は詳細かつ明解である必要があるが、
（中略）
そして「運用・保守向けに必要」であるなら、実際の処理の内容を詳細に記述することよりも、なぜそのような設計になっているのかという点を意識して記述した方がよい。これは実際の保守開発においては、内部設計書を細かく読むよりも、ソース・コードを読むことの方が多いため、ソース・コードを読むに当たっての手引きとなるようなドキュメントが望ましいのである。
ツールを使ったドキュメント作成技法（前編） − ＠IT
太字は、私が強調したところです。要するに、「詳細設計書を基に実際の開発を行う」ときは【HOW】を記述する必要があるが、運用・保守向けに必要」ならば【WHY】を示さなければならないということかな。考えてみれば、保守時はどうやって実装されているかなんて、ソースコードを見れば書いてあるので、そっちを見た方が早いし正確なのもそうですね*3。
あとは、運用・保守時に欲しいものはテストデータの作り方？画面とか帳票系の機能は比較的分かりやすいしユーザマニュアル等が用意されるでしょうが、バッチで動くような機能だとどんなデータがインプットとして入るかイメージしにくいのですよね。机上でソースを追っていくより、データを流してデバッグで確認した方が早いこともあるでしょうし。
（順調に行けば）今携わっているシステムが6月末カットオーバーなので、今は不具合対応をしながら空いた時間で引継資料を作成しているところですが、何を書いていいかがピンときてなかったのですよ。
ですが、とりあえず自分の中では一つ方向性が見出せました。以下のことを念頭に置いて、作業を進めることにしましょう。
- 「なぜこのような設計・実装方法を採用したのか」を明文化する
- （特にバッチ系は）インプット・アウトプットを概略で分かるようにする
- テストデータを容易に作れるようにするため
何かご意見があったら、コメント・トラバ・ブコメ待ってます♪
