開発ドキュメント

ソフトウェアを開発する際に作成する一般的なドキュメントの種類とその記述内容を示す．

ドキュメントの種類

ソフトウェア開発ドキュメントを目的別に分類すると次のようになる．

要求仕様書
開発するシステムの機能，性能，インタフェース，データベースなどに関する要求条件を規定するドキュメントである．また，開発上の制約 (動作環境，実装上の制約 (OS，言語)，コスト，品質など）を明確にする．
設計書
開発するプログラムに関する仕様および実装方法を規定するドキュメントである．開発工程ごとに，基本設計書 (BI工程)，機能設計書 (FD工程)，詳細設計書 (DD工程)などを作成する．
操作説明書 (マニュアル)
プログラムのインストール方法や利用方法，操作方法などを記述する．プログラムの利用者向けのドキュメントである．
開発関連ドキュメント
プログラムの開発を円滑に進めるためのドキュメントである．また，開発に関する各種記録を残す目的のドキュメントもある．
- 開発計画書 (プロジェクト計画書)
- 作業標準
- 試験手順書，試験報告書
- 品質管理計画書，品質管理帳票(障害処理票，品質管理図など)
- 開発報告書 (プロジェクト報告書)

どのようなドキュメントを作成するかは，プログラムの種類，性格，対象ユーザなどに依存し，開発計画の段階で決定される．

設計書

基本設計書
システムに対する要件定義である機能要件，非機能要件，制約条件に基づいて，次のような項目を明確にする．
- 方式設計（アーキテクチャ設計）
  ハード／ソフトの構造（アーキテクチャ）や実装方針
  実行環境，開発環境，テスト環境などの設計条件
- 機能設計 (アプリケーション設計)
  ソフトウェアとして実装する機能，データベース，画面や帳票などのユーザインタフェースなど
- その他の設計
  システムの非機能要件で定義された性能，信頼性，セキュリティ，運用などに関する設計
機能設計書
機能設計書で記載すべき代表的な項目例を示す．
- 設計条件
  基本設計書と重複するが，より詳細化，具体化する．
  - 設計方針 (プログラムの基本的な設計，製造方針)
  - 動作環境（OS環境，ソフトウェア環境，コンパイラ環境等）
  - 試験環境 (動作確認を行う試験環境)
- 機能条件
  プログラムが実現すべき機能の全体像と各機能の位置づけを明確にする．
- 機能仕様
  プログラム内の各機能の外部仕様を規定する．
- 構成仕様
  プログラムの構造を規定する．
- インタフェース仕様
  他プログラムやプログラムの利用者との関係など守るべきインタフェースを規定する．
詳細設計書 (プログラム設計書)
詳細設計書は，機能設計書で定義された機能をプログラムとしてソースコードに変換する過程において，実装方法を詳細化するものである．
- プログラム構造(モジュール分割)とモジュール間インタフェース
- データ構造（テーブル設計，画面/帳票イメージなど）
- 各機能 (モジュール)の実現方法 (処理フロー)
- 単体テストのためのテスト仕様
詳細設計書の必要性については，次のような指摘がある．
- 詳細設計とコーディングの担当者が異なる場合には詳細設計書が必要になるが，そういうケースは少ない．詳細設計とコーディングは連続した類似の作業であり．全体として作業が非効率になる．また，ソースコードとの 2重メンテナンスになる．
- オブジェクト指向言語や関数型言語の普及により，わざわざ自然言語で詳細設計書を作ることの意味が薄れてきている．自然言語で記述された設計を形式言語に変換する作業は無駄である．
- 詳細設計書は，一度作成されるとコーディング段階で変更があったとしても修正が漏れたり，正しく保守されることが少ない．そのため，詳細設計書は誰も見なくなる．
詳細設計書については，上記のようにその必要性について様々な議論がある．作成するプログラムの種類や規模，性格にもよるが，次のような方針を採ることが多いと思われる．
- 機能設計書から実装が容易には導き出せない，あるいは種々の実装方法がある場合に，その具体的方法を記載する．
- プログラムの主要な流れ，論理が複雑な部分など，ソースコードを理解する助けとなる部分を重点的に記載する．また，ソースコードに記述することのできない制約，保守情報などを記載する．
- ソースコードと一対一対応するような詳細設計書は作成しない．保守のためのドキュメントが必要な場合は，Doxygen，Javadoc などのツールを用いてソースコードから自動生成する (事前に対応したコメントをソースに記述しておく)．
いずれにしろ，詳細設計書はその目的を明確にして作成すべきである．実装工程の進捗に役立つのは勿論，保守用のドキュメントとして役立つこと，検収のためのテスト作成に役立つことなどである．

開発管理

開発計画書 (プロジェクト計画書)
開発計画書では，次のような項目を記載する．
- プロジェクト概要
  開発の背景，目的，目標，開発方針などを明確にする．
- システム要件
  開発するシステムのハードウェア／ソフトウェア／ネットワークなどのシステム構成を明確にする．また，システムに対する主要な機能要件，非機能要件を明確にする．
- 作業内容
  プロジェクトの作業内容と作業量を明確にし，作業項目の順序付けを行う．
- スケジュール
  プロジェクト全体の作業工程とそのスケジュールを明確にするとともに，主要マイルストーンを定める．
- 開発工数 (コスト)
  プロジェクトに必要とされる要員数とその資格要件を作業工程毎に明確にする．人件費を含めプロジェクトで使用予定の費目とその費用を見積る．
- プロジェクト体制
  顧客，協力会社を含めて開発体制 (プロジェクトチームを構成する担当者) と役割分担を明確化する．
- コミュニケーションルール
  顧客，協力会社を含めて会議体の構成とその目的，役割りおよび責任を明確にする．メール，情報共有システム，議事録，質問・回答票，緊急連絡網などのルールを決める．
- 品質目標
  開発工程に沿って品質をどの様に確保するか，その仕組みと作業内容を明確にするとともに各開発工程での品質目標を定める．
- リスク管理
  リスクの管理方法を定めるとともに，計画段階でのリスクとその対策および対応状況を明示する．「リスクの背景・原因 → 引き起こされる事象 → 影響」の構造が確認できるようにリスクを記述する．
- 生産物
  プロジェクトの各工程における生産物を定める．
作業標準
ソフトウェア開発における生産性の向上と品質向上のために必要に応じて開発作業標準を定める．次のような項目が対象となる．
- ソフトウェア構成管理
- 変更管理
- 品質管理
- コーディング規約
試験手順書，試験報告書
試験項目を消化するための試験手順，消化基準を明確化し，試験手順書として文書化する．机上でしか確認できない試験項目は，その確認手順とその基準を明記する．試験終了後，試験結果を試験報告書としてまとめる．
品質管理計画書
品質管理対象，品質管理指標と目標値，品質管理作業手順，品質評価方法など品質管理に関する項目を記載する．また，品質管理に使用する各種帳票 (障害処理票，品質管理図など) を規定する．
開発報告書 (プロジェクト報告書)
開発報告書では，次のような項目を記載する．
- 要求仕様とその実現方法
- 生産物
  作成したプログラム，ドキュメントの種類と規模，生産性
- 品質報告
  試験方法，試験結果(バグ摘出状況)，品質見解など
- 性能報告
  処理性能の評価，セキュリティの評価など
- 総括
  反省点，今後の開発，保守等への提言など