イノベーション エンジニアブログ


株式会社イノベーションのエンジニアたちの技術系ブログです。ITトレンド・List Finderの開発をベースに、業務外での技術研究などもブログとして発信していってます!


このエントリーをはてなブックマークに追加

システム開発で作られるドキュメントについて考えてみる

こんにちは。 エンジニアのNew塚本です。

私、今年が本厄でして、去年からロクなことが起きておりません。
車検をあげた次の月にヘッドライトが切れ、次の月になんと高速でタイヤがバースト、
さらに、上野の件や、車をぶつけられたり。
まだまだありますが・・・ホンキでお祓いを考えてます。

気を取り直して!
今回は、システム開発で作成されるドキュメントについて考えてみました。

きっかけ

私は長年、ウォーターフォールモデルでの開発をしていました。
上流から下流へ水が流れる様に工程をっていう、あれです。

さらに開発標準なるものが用いられ、それに則り各工程での成果物(ドキュメント類)が決められてました。 (正直これいる?みたいなものもありましたが。)

また、アジャイル開発も経験していますが、
そこは極端でしたので一切ドキュメントは書きませんでした。

ドキュメント(設計書)って、誰の為に何で必要なのか。

そんなモヤっとした感じを、今回考えてみました。

まず・・・

私の経験から、システム開発でお目にかかるドキュメントは、大まかにはこんなものがあります。

・要求仕様書
クライアントが開発を請負う人に対し、開発を依頼するシステムの要件を文章化したものです。 大体、5W1H(目的、予算、納期、運用)で記載されている事が一般的です。

・要件定義書
システム開発側から要求仕様に対する実現性を纏めた資料

・基本設計書
システム化に向けて大まかに要件を纏めた設計書

・詳細設計書
基本設計で定義した機能を、処理フローや入出力などを纏めた設計書

・プログラム設計書
プログラムをどの様に実装するかを纏めた設計書

・テスト仕様書
試験観点、テスト項目、バグ検出密度などを纏めた設計書

それぞれ何の為に必要か?

今回は、設計工程でのドキュメント(要件定義、基本設計、詳細設計)について考えてみます。

・要件定義書
抽象的な要求仕様をシステム化するのですから、認識ずれを起こさないことが大切です。
やる事や、やり方などを決めておく必要があります。 詰め切れない内容は、申し送り事項として、抜け漏れを起こさない事が必要です。また、重要な点はクライアントの視点で記載する事だと思います。

・クライアントと開発者が、システム全体像を共有をするために必要
・やる事を明確にする事が必要

・基本設計書
システム化に向け、抽象的だった要件をより具体的に落とし込む必要があります。
また、画面が必要であればレイアウトや動作についても決めておく必要があります。このあたりから、開発者の視点で記載する事が増えてくると思います。

・クライアントと開発者が、具体的な要件を共有をするために必要
・大まかな挙動はすり合わせ、システムとして必要な要素を洗い出す

・詳細設計書
基本設計から更に詳細化しますが、 処理フロー定義や、エンティティの物理設計など開発者の視点で記載されていきます。また、プログラム設計書としてプログラムの内容を文章化したりします。

・開発者がプログラムを作る設計図として必要
思い返してみると・・・

クライアントと基本設計のレビューをした際に、 何だか「???」みたいな反応になった経験はありません? 私はありました。

要件定義では、「そうだね!」みたいな反応が、機能定義など踏み込んだ話になると「・・・・・うん。」みたいな微妙な反応。

話し方のスキルもあるかとは思いますが、

これ、考えてみました。

開発者の視点で内容がどんどん追加されていくと、 クライアントの視点からはどんどん離れて行くと思うんですよね。 いわゆるギャップというか、内容難しくね?みたいな感じで。

感想

当たり前な話ですが、何のために必要なのかを意識する事って重要ですね。ドキュメントは特にこの意識が大切だと再認識しました。

でもなんですが、詳細設計書とかプログラム設計書って開発者が理解できれば良いと思ってます。そもそも、メンテナンス大変じゃないですか。追加開発やバグ修正などで、プログラムは変更されますが、この部類の設計書はおざなりになり易く、だんだんずれてきませんか?

なので、私はプログラム設計書の作成は反対派です。プログラムのコメントからドキュメント化できる、phpDocumentor派になりました。

おわり