「誰」に対して「何」を説明するためのものかを考える

本連載では、現場における開発ドキュメントの書き方について説明します。第3回ではウォーターフォールモデル、第4回ではアジャイルモデルを取り上げます。その前段となる今回は、開発ドキュメントをまとめる上で開発モデルに関係なく大切となる視点について考えてみます。

ソフトウェア開発の流れは、一般的なものづくりのそれと変わるところはありません。「何を作るか」「どのように作るか」を考え、実際に「作り」、最後に「確認する」という流れです。

これをソフトウェア開発に当てはめてみると、「何を作るか」は要件定義、「どのように作るか」は設計、実際に「作る」はプログラミング、「確認する」はテストに該当します。ウォーターフォールモデルと繰り返し型やアジャイルモデルでは、順番に1回だけか、それとも何度も繰り返し行うかという違いはありますが、大きな流れとしては変わりません（なお、今回の連載は主に設計、実装に携わるエンジニアが作成するドキュメントをターゲットにしていますので、要件定義は対象外とします）。

この流れの要所でソフトウェア開発の関係者の誰かに何かを説明するために、開発ドキュメントは作成します。それぞれの部分で「誰」に対して「何」を説明する必要があるかを考えることが大切です。今回は重要な3組の「誰」と「何」を取り上げます（図1）。

まず、最初の「誰」は「顧客」です。顧客がソフトウェアで実現したいことは要件定義でまとめられます。開発業者は、要件定義の結果に基づき、ソフトウェアをどのように作るかを考え、顧客に説明する必要があります。「何」に当たるのは「ソフトウェアをどのように作るのか」になります。

次の「誰」は「プログラマ」です。顧客に説明した「ソフトウェアをどのように作るのか」を、プログラムとしてどのように作ればよいかを、プログラマに伝える必要があります。「何」に当たるのは「プログラムをどのように作ればよいか」になります。

最後の「誰」は「テスタ」です。プログラマが作成したソフトウェアを、どのように確認すればよいかをテスタに伝える必要があります。「何」に当たるのは「ソフトウェアをどのように確認すればよいか」になります。

「顧客」に対して「ソフトウェアをどのように作るのか」を説明する

要件定義ではソフトウェアで実現することを決めますが、どのように実現するかまでは踏み込みません。そのため要件定義の結果をソフトウェアとしてどのように作るかを考える必要があります。

では、顧客が確認したい「ソフトウェアをどのように作るのか」とは何でしょうか。それは、ソフトウェアの「外部に対する振る舞い」です。

顧客の立場から見ると、ソフトウェアの内部がどのように作られるかはあまり重要でなく、画面の使い勝手や他システムとの連携といった外部に対する振る舞いの方が重要です。顧客はソフトウェアの完成した姿を想像し、望んだものができるのかを早期に確認したいと考えています。開発側はそれに答えるために、外部に対する振る舞いを開発ドキュメント（以下、顧客向けドキュメント）にまとめ、説明する必要があるのです。

しかし、この「外部に対する振る舞い」の説明は概要レベルでしかされないことが多く、画面の使い勝手や他システム連携などは後工程に送られることが少なくありません。そのような状態では、顧客はソフトウェアの完成した姿を想像できませんので、望んだものとの相違点の指摘はどうしても動くものが見られるようになってからになります。そのためプログラミングやテストの工程になってはじめて問題が発覚するのです。皆さんもご存じの通り後工程になる程、対応が困難になります。

顧客が開発の初期段階でソフトウェアの完成した姿を想像できれば、プログラミングが本格化する前に具体的な指摘が可能になります。まだ余裕のある状況で調整ができれば、後工程での問題の発生を抑えることができます。ウォーターフォールモデルでは、要件定義の直後に基本設計や外部設計という工程が定義されています。これはその工程がそれだけ重要な作業であることのあらわれでしょう。

ソフトウェア開発の本来の姿は、顧客がやりたいことに対して自分たち（開発業者）の状況を考慮しつつ、最適なソフトウェアを提案する仕事です。ソフトウェアの専門家である開発業者は、これから作るソフトウェアの姿を、顧客により具体的に想像してもらえるように、わかりやすく正確な開発ドキュメントを作成する必要があります。 次のページ