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

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

Dropの開発ドキュメントは、ドキュメントの利用対象者によって「保守ドキュメント」と「利用ドキュメント」に分類される（図30-1）。また、開発対象によって、それぞれシステム用とコンポーネント用に分類される。

Dropドキュメントを使う場合は、この分類の意味とそれぞれのドキュメントの目的を理解した上で、ドキュメントに記載すべき内容を決めなければならない。

表30-1 Dropドキュメント分類

分類		対象者	説明
利用	システム利用	システム利用者 （ユーザ）	システムを利用するためのドキュメント。操作マニュアルやインストールガイドなど、システム利用者のレベルに合わせて記述する。システム保守のための内容を記載すべきではない。
	コンポーネント利用	コンポーネント利用者 （ADG & ODG）	コンポーネントを利用するためのドキュメント。コンポーネントの使い方を簡潔に分かりやすく記述する。コンポーネント保守の情報を記載すべきではない。
保守	システム保守	システム開発者 （ADG）	システムの開発・保守に必要となるドキュメント。システムの構成や仕組みを簡潔に解説する。
	コンポーネント保守	コンポーネント開発者 （ODG）	コンポーネントの開発・保守に必要となるドキュメント。コンポーネントの移植・拡張に役立つ情報を簡潔に解説する。

表30-2に、Dropドキュメントの一覧を開発フェーズ別に示す。この中で「種別」が、「利用」「保守」「計画」の何れかになっている。「計画」とは、「保守」の一種であるが、単一プロジェクトにおけるドキュメントではなく、チームの長期的なルールやスケジュールなどを定めているものである。

表30-2 Dropドキュメント一覧

利用フェーズ	ドキュメント名	種別	概要説明
問題領域分析
	基本計画書	計画	システム開発の計画スケジュール
	要求仕様書	保守	システムの要求を定めている
	開発基盤検討書	保守	システムを開発するソフトウェア基盤を定める
システム共通設計
	システム開発環境標準	計画	システム共通の開発ルールを定める
	システムアーキテクチャ仕様書	保守	システム共通部分の設計内容
	システム機能仕様書	保守	要求をシステム機能に落としたもの
	システム操作説明書	利用	ユーザ操作マニュアル
アプリケーション 設計・実装
	アプリケーション設計書	保守	アプリケーションとしての仕様を定める
	テスト項目票	保守	テスト項目の消化・非消化が書かれる
システム テスト・評価
	バグシート	保守	バグの発生日・解決日が書かれる
コンポーネント分析
	コンポーネント開発計画書	計画	パッケージ単位の開発計画
	パッケージ開発環境標準	計画	コンポーネントを開発する上での統一的なルール
	パッケージ利用解説書	利用	コンポーネント群やフレームワークの利用解説
	パッケージ仕様書	保守	パッケージの設計概念などを説明する
コンポーネント 設計・実装
	コンポーネントリファレンス	利用	公開クラスの説明、公開メソッドの説明、インタフェースの解説など
	テスト項目票	保守	テスト項目の消化・非消化が書かれる
パッケージ テスト・評価
	バグシート	保守	バグの発生日・解決日が書かれる

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

ソフトウェア開発においてドキュメントを残すことは、ソフトウェアの正しい利用を促進し、ソフトウェアの品質を保つ意味で重要なものである。しかしながら、せっかく作ったドキュメントも分厚い枕としてしか使われないこともよくあることだ。誰も使わないドキュメントは、コストがかさむばかりでなく、無駄な時間を浪費してしまった開発者の意欲をなくしてしまうことになりかねない。

このようなドキュメント作成の問題をプロジェクト管理者（システム管理者、コンポーネント管理者）はどう扱うべきなのだろうか？当然のことながら、Dropドキュメントをどの程度プロジェクトに採用するかはプロジェクト管理者が決めることである。プロジェクト管理者が、対象とするプロジェクトの形態や規模にあわせてドキュメントを選択する責任がある。

Dropドキュメントを採用し、ソフトウェア開発にドキュメント効果を最大限発揮するためのポイントを以下に示そう。

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

ドキュメントのコストを考慮する

ドキュメントを作成するには期間と労力がかかるのは当然の話である。管理者は、ソフトウェア工数、及び期間算定の中にドキュメント作成コストを充分加味しておかなければならない。また、ドキュメント作成の投資対効果バランスのセンスが必要とされる。

厚みで勝負は最低。内容で勝負すべし

内容がなく厚みだけがあるドキュメントは無意味であるだけではなく、ソフトウェアの保守性を低下させてしまう。管理者は、ドキュメントの枚数分だけ保守の手間がかかってしまうことを肝に銘じておかなければならない。高品質のドキュメントとは、目的にあった内容を少ない量で示しているものである。たとえ１枚であっても内容によっては優れたドキュメントとして評価できるものも当然ながらある。

ドキュメントの意味を理解している人が作る

作ろうとするドキュメントの必要性、種別（保守・利用）、利用者の技術レベルなどについて充分理解したメンバにドキュメントを書かせること。無意味なドキュメントを残してはならない。

ドキュメントの評価を必ず行う

「第２５章 　システムテスト・評価フェーズ」、「第２８章 　パッケージテスト・評価フェーズ」の中で、作成されたドキュメントに対して以下の評価を必ず行う。評価の結果は、次期開発に向けたドキュメント対策としてチームの中で掲げられる。

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

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

プロジェクト管理面におけるドキュメント作成考慮点

ドキュメントヘッダを付ける

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

表30-4　ドキュメントの表紙に記載される内容

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

全体作業リストと各メンバの作業リストを作成する

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

表30-5　個人別作業チェックリスト

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

ドキュメントの清書を遅らせる

ドキュメントの記載内容は、開発中に必要なものと開発後に利用価値が生まれるものとに分かれる。たとえば、ADGがコンポーネントを利用する際に「パッケージ利用解説書」と「コンポーネントリファレンス」があれば何も言うことがない。しかしながら実際の開発では、ADGの開発とODGのコンポーネント開発が同時並行的に行われることが多いだろう。このようなケースでは、きちんと完成されたドキュメントを待つよりも、DROで作成されたオブジェクトレイアウトカードと簡単な手書きのサンプルや解説をいち早く提供された方が、両者ともストレスなくスムーズに開発が進むことになるだろう。このように、開発中はラフな仮ドキュメントを使って、開発が一段落した評価フェーズにて正式なドキュメントを作成することは、効率化を図る上で有効な手段である。

ネットワークを有効に利用する

最新情報を低コストで素早くドキュメントとして作成し配布するには、社内ネットワークを効率的に使いこなす必要がある。ドキュメントをファイルサーバに入れておき、いつでも参照できるようにするとよい。それを正しく運用するには、ネットワークを利用したドキュメント管理のルール化が欠かせないだろう。

なお回覧方法として、チーム内、社内にWWWサーバを起ち上げ、pdfファイルやhtmlファイルを使ってドキュメントを参照させることができれば、ビジュアルなドキュメントを統一されたブラウザインタフェースによって参照することができるようになる。このためには、プロジェクト管理者はhtml,pdf対応ツールなどを買い揃えることもよいだろう。

メールは手軽で高速な情報伝達手段である。メールを使って進捗やバグの通知を行うようにするとよいだろう。しかし、プロジェクトにおける意志決定を下す手段としては効果的ではない。意志決定の過程をプロジェクトの全メンバが参加するメーリングリストに流してしまうと、全メンバが中途半端な情報を見ることになり、無駄なばかりか混乱を招いてしまうことになるだろう。プロジェクトにおけるメールの利用についてもルール化しておく必要がある。

ドキュメントチームを作る

開発者は、なかなかユーザ利用者のレベルに合わせたドキュメント記述ができないことも多い。そこで、製品開発などでは、開発チームとは別にドキュメントチームを結成して、そのチームでシステム操作説明書やパッケージ利用解説書などを作成させ、開発チームにチェックさせるようにすればドキュメントの品質を向上させることができる。

ドキュメント簡略化

小規模開発におけるドキュメント簡略化

小規模開発でDrop標準ドキュメントに沿ってドキュメントを作成するのは少し大げさのような気がするだろう。

以下に、小規模開発の例として、「第１０章 　開発サイクル基本形」で解説した単一アプリケーション型を例として、どの程度簡略化されるのか解説する。この例のアプリケーションは、開発期間３ヶ月、開発者２名を想定したものである。また、約２割程度がコンポーネント化されたことにしよう。

省略可能と記したドキュメントは、必要に応じて他のドキュメント項目にまとめればよい。なお、ドキュメント枚数はあくまで目安として示したものである。

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

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

この記事のトップへ