開発ドキュメント編

第３０章　開発ドキュメントの考え方

３０．１　標準ドキュメント一覧

３０．２　Dropドキュメントの作成法

　ソフトウェア開発においてドキュメントを残すことは、ソフトウェアの正しい利用を促進し、ソフトウェアの品質を保つ意味で重要なものである。しかしながら、せっかく作ったドキュメントも分厚い枕としてしか使われないこともよくあることだ。誰も使わないドキュメントは、コストがかさむばかりでなく、無駄な時間を浪費してしまった開発者の意欲をなくしてしまうことになりかねない。
　このようなドキュメント作成の問題をプロジェクト管理者（システム管理者、コンポーネント管理者）はどう扱うべきなのだろうか？当然のことながら、Dropドキュメントをどの程度プロジェクトに採用するかはプロジェクト管理者が決めることである。プロジェクト管理者が、対象とするプロジェクトの形態や規模にあわせてドキュメントを選択する責任がある。
　Dropドキュメントを採用し、ソフトウェア開発にドキュメント効果を最大限発揮するためのポイントを以下に示そう。

高品質ドキュメント作成ノウハウ

• ドキュメントのコストを考慮する
  　ドキュメントを作成するには期間と労力がかかるのは当然の話である。管理者は、ソフトウェア工数、及び期間算定の中にドキュメント作成コストを充分加味しておかなければならない。また、ドキュメント作成の投資対効果バランスのセンスが必要とされる。
  
  
• 厚みで勝負は最低。内容で勝負すべし
  　内容がなく厚みだけがあるドキュメントは無意味であるだけではなく、ソフトウェアの保守性を低下させてしまう。管理者は、ドキュメントの枚数分だけ保守の手間がかかってしまうことを肝に銘じておかなければならない。高品質のドキュメントとは、目的にあった内容を少ない量で示しているものである。たとえ１枚であっても内容によっては優れたドキュメントとして評価できるものも当然ながらある。
  
  
• ドキュメントの意味を理解している人が作る
  　作ろうとするドキュメントの必要性、種別（保守・利用）、利用者の技術レベルなどについて充分理解したメンバにドキュメントを書かせること。無意味なドキュメントを残してはならない。
  
  
• ドキュメントの評価を必ず行う
  　「第２５章　システムテスト・評価フェーズ」、「第２８章　パッケージテスト・評価フェーズ」の中で、作成されたドキュメントに対して以下の評価を必ず行う。評価の結果は、次期開発に向けたドキュメント対策としてチームの中で掲げられる。
  
  

  評価項目	評価の方法
  ドキュメントの必要性	プロジェクトとして本当に必要なドキュメントだったのか？
  使われなかったドキュメント	なぜ使われなかったか？どうすれば使えたか、または、不必要なものか？
  書くべきドキュメント	なぜ書かなかったのか？その影響はどうだったか？
  分厚いドキュメント	なぜ分厚くなったか？意味のある情報か？改善策は？
  適切な情報	ドキュメント利用者にとって適切な内容か？たとえば、保守と利用を混同して書いていないか？
  古くなった情報	新しくする必要があるか？するとすれば何時やるか？

  表30-3　ドキュメント評価方法
  
  

• ドキュメントヘッダを付ける
  　管理面で重要と判断されたドキュメントについて、下記のヘッダ項目を表紙に付加して管理する。
  
  

  ヘッダ項目	説明
  通版	プロジェクトにおけるドキュメント管理番号
  修正履歴	日付、ドキュメントバージョン、訂正・追加内容を記述する
  所属名・作成者名	作成者の所属部と氏名を記入

  表30-4　ドキュメントの表紙に記載される内容
  
  
  
• 全体作業リストと各メンバの作業リストを作成する
  　Dropの標準ドキュメントには含まれていないが、プロジェクトの進行過程での決定事項（決めたこと）に対し、具体的に「やるべきこと」まで落とした作業予定一覧を担当メンバに配布する（または作成させる）。各メンバは、「やるべきこと」の完了予定日と完了日を記録しておき、進捗状況を管理者に知らせる。下記は、システム設計・実装フェーズにおける作業リストの例である。
  
  

  完了予定日	完了日	内容
  10/10	10/10	動作状態取得機能の改善
  10/12	10/11	10/8のレビューによるViewの改善
  10/15	/	10000行越えた際のログ出力バグの改善
  10/20	/	Viewを交えた結合テスト
  /	/	：

  表30-5　個人別作業チェックリスト
  
  
  
• ドキュメントの清書を遅らせる
  　ドキュメントの記載内容は、開発中に必要なものと開発後に利用価値が生まれるものとに分かれる。たとえば、ADGがコンポーネントを利用する際に「パッケージ利用解説書」と「コンポーネントリファレンス」があれば何も言うことがない。しかしながら実際の開発では、ADGの開発とODGのコンポーネント開発が同時並行的に行われることが多いだろう。このようなケースでは、きちんと完成されたドキュメントを待つよりも、DROで作成されたオブジェクトレイアウトカードと簡単な手書きのサンプルや解説をいち早く提供された方が、両者ともストレスなくスムーズに開発が進むことになるだろう。このように、開発中はラフな仮ドキュメントを使って、開発が一段落した評価フェーズにて正式なドキュメントを作成することは、効率化を図る上で有効な手段である。
  
  
  
• ネットワークを有効に利用する
  　最新情報を低コストで素早くドキュメントとして作成し配布するには、社内ネットワークを効率的に使いこなす必要がある。ドキュメントをファイルサーバに入れておき、いつでも参照できるようにするとよい。それを正しく運用するには、ネットワークを利用したドキュメント管理のルール化が欠かせないだろう。
  　なお回覧方法として、チーム内、社内にWWWサーバを起ち上げ、pdfファイルやhtmlファイルを使ってドキュメントを参照させることができれば、ビジュアルなドキュメントを統一されたブラウザインタフェースによって参照することができるようになる。このためには、プロジェクト管理者はhtml,pdf対応ツールなどを買い揃えることもよいだろう。
  　メールは手軽で高速な情報伝達手段である。メールを使って進捗やバグの通知を行うようにするとよいだろう。しかし、プロジェクトにおける意志決定を下す手段としては効果的ではない。意志決定の過程をプロジェクトの全メンバが参加するメーリングリストに流してしまうと、全メンバが中途半端な情報を見ることになり、無駄なばかりか混乱を招いてしまうことになるだろう。プロジェクトにおけるメールの利用についてもルール化しておく必要がある。
  
  
  
• ドキュメントチームを作る
  　開発者は、なかなかユーザ利用者のレベルに合わせたドキュメント記述ができないことも多い。そこで、製品開発などでは、開発チームとは別にドキュメントチームを結成して、そのチームでシステム操作説明書やパッケージ利用解説書などを作成させ、開発チームにチェックさせるようにすればドキュメントの品質を向上させることができる。

• 小規模開発におけるドキュメント簡略化
  　小規模開発でDrop標準ドキュメントに沿ってドキュメントを作成するのは少し大げさのような気がするだろう。
  　以下に、小規模開発の例として、「第１０章　開発サイクル基本形」で解説した単一アプリケーション型を例として、どの程度簡略化されるのか解説する。この例のアプリケーションは、開発期間３ヶ月、開発者２名を想定したものである。また、約２割程度がコンポーネント化されたことにしよう。 省略可能と記したドキュメントは、必要に応じて他のドキュメント項目にまとめればよい。なお、ドキュメント枚数はあくまで目安として示したものである。
  
  

  利用フェーズ	ドキュメント名	種別	概要説明
  問題領域分析	基本計画書	計画	１枚程度
  	要求仕様書	保守	４、５枚程度
  	開発基盤検討書	保守	省略可能。要求仕様に記載する。
  システム共通設計	システム開発環境標準	計画	１枚程度
  	システムアーキテクチャ仕様書	保守	省略可能。
  	システム機能仕様書	保守	省略可能。
  	システム操作説明書	利用	６、７枚程度
  アプリケーション設計・実装	アプリケーション設計書	保守	３、４枚程度
  	テスト項目票	保守	１、２枚程度
  システムテスト・評価	バグシート	保守	バグが発生した枚数
  コンポーネント分析	コンポーネント開発計画書	計画	１枚程度
  	パッケージ開発環境標準	計画	１枚程度
  	パッケージ利用解説書	利用	２、３枚程度
  	パッケージ仕様書	保守	１、２枚程度
  コンポーネント設計・実装	コンポーネントリファレンス	利用	コンポーネント１個に対して１枚程度
  	テスト項目票	保守	１枚程度
  パッケージテスト・評価	バグシート	保守	バグが発生した枚数

  表30-6 Dropドキュメントの簡略化例