システム開発では、実際に開発しているシステムだけではなく、さまざまなドキュメントも一緒に納品することが一般的です。しかし、システム開発の過程で、なぜドキュメントを作成する必要があるのか疑問に感じる方もいるかもしれません。
ドキュメントには多くの種類があり、具体的にどのような内容のドキュメントを作成するかは、開発会社によっても異なります。
この記事では、システム開発におけるドキュメントの必要性、またドキュメントの種類や作成時のポイントについて説明します。
ドキュメントは、システム開発の工程のなかで作成する、成果物の一種です。
では、そもそもなぜドキュメントを作成する必要があるのでしょうか。システム開発においてドキュメントを作成する必要性は、おもに以下2点にあります。
システム開発では、クライアントと開発会社が同じ完成形のイメージを持ち、開発を進めることが重要です。クライアントの求めるシステムを作れていなければ、無駄な手戻り作業・コストも発生しますし、そもそも開発は失敗といえるでしょう。
予算・デザイン・実装する機能などに関するドキュメントを共有することで、クライアントとしても安心して開発を任せられます。基本設計の工程までは、クライアントと密にコミュニケーションを取りながら進めることも多いため、イメージと異なる部分があれば遠慮せずに意見を出してください。
クライアントと共有するためのドキュメントもありますが、プログラミングに関するものなど、開発会社のエンジニア・プログラマーに向けたドキュメントもあります。
具体的にどのような言語で、どのようにプログラミングしていくのかなど、技術的な面に関してもドキュメントで共有しておくことで、開発をスムーズに進められるでしょう。
システム開発では、1人ではなく多くのエンジニア・プログラマーが携わります。工程によって担当する技術者は異なることが一般的なので、例えば設計〜開発(プログラミング)へと滞りなく移行するためにも、ドキュメントは必要なのです。
また、ドキュメントを作成しておけば、開発途中で仕様変更が生じた際にどの部分をどう変更するのか、共有しやすくもなります。
システム開発は一度完成したら終了ではなく、実際に運用していくなかで見つかるトラブル・バグなどを随時修正し、アップデートしていく必要があります。このような保守・運用を行なう場合に、設計やテストなどに関する情報が書かれたドキュメントを活用することで、修正点を見つけやすくなるでしょう。
さらに、開発からしばらく経つと、開発会社の担当者や体制が変わることもあります。そのときにもドキュメントがあれば、システム開発全体の流れを容易に把握できるため、引き継ぎなどをスムーズに行なえるのです。
ここからは、システム開発を進めるなかでどのようなドキュメントを作成するのか、その一例を開発の工程別に紹介します。ただし、開発会社や進め方によって何を作成するのかは変わるので、参考程度にお考えください。
システム開発はいきなり始まるのではなく、クライアントから発注を受けてから始まります。そのため、開発自体の工程ではありませんが、開発依頼はドキュメントが発生する最初の工程といえるでしょう。
Webシステムの場合、ECサイトにしたいのか、ポータルサイトにしたいのかで、適切なアプローチが変わります。このように、システム開発の目的・解決したい課題・制約条件などの概要を記したのが、RFP(提案依頼書)です。RFPの内容を受けて、開発会社はどのような開発手法やソリューションを用いて、どれくらいの予算で請け負えるかなどを検討します。
なお、提案依頼書を作成するのは発注者で、次の要件定義書以降は開発会社が作成します。
【RFP(提案依頼書)に盛り込む内容】
システム要件・予算・開発の目的・運用方法・納期 など
要求定義と要件定義の違いを一言で表すと、以下のようになります。
【要求定義】:どのような製品を作るのかユーザーが求める仕様を定義すること。
【要件定義】:実装すべき機能・達成すべき要件などの仕様を定義すること。
要求定義では、クライアントがどのようなシステムを開発したいのかをヒアリングし、要求を洗い出します。例えば、「実店舗の集客に関して伸び悩んでいる現状で、Web上での集客を強化するためにECサイトを構築したい」という場合、具体的にどのような機能やデザインを求めているのかを要求定義でアウトプットします。
この要求定義に基づいて、実際に実装可能なシステム要件に落とし込む作業が要件定義です。上記ECサイトの例でいえば、集客の課題を解決するにはどのような決済システムにするのか、他サービスとどのように連携するのかなどを鑑みて、要件を定めます。
要件定義書には、実現可能な機能や、開発全体に必要なコスト・人員・開発工数などについての見通しも含め、開発に関する要件について明記します。
また、機能要件だけではなく、非機能要件についても要件定義書でまとめておくことが望ましいでしょう。
機能要件とは、開発するシステムに対してクライアントが要望する最低限の「機能」のことです。一方で非機能要件とは、機能要件以外の、システムの品質に関するものを指します。
システムをスムーズに運用できるかは、非機能要件がカギを握っています。
【要件定義書に盛り込む内容】
要求・要件・機能の概要・コスト・人員・開発工数・実現方法 など
関連記事:要件定義と要求定義の違いとは?それぞれの考え方や定義書に記載すべき項目
基本設計とは、画面のレイアウトやボタンの配置など、システムの外観部分の設計のことです。Webシステムでいえば、どこをクリックするとどのように機能するのか、などを検討するのが基本設計といえます。
運用される場面を想定して、具体的な画面設計・バッチ設計・データベース設計などを記したのが基本設計書です。なお、基本設計で作成する詳しい内容については、以下の記事を参考にしてください。
関連記事:システム開発の基本設計とは?作成ツールや作成時のポイントも説明
【基本設計書に盛り込む内容】
画面設計・システム設計・バッチ設計・外部インターフェース設計・データベース設計・ER図 など
基本設計書の内容を、現実的にどのように実装・プログラミングするのかを決めるのが詳細設計です。例えば、基本設計で定めたWebシステムのレイアウト・ボタンの機能などを実現する、具体的な方法を記します。
基本設計ではまだ大枠しか決まっていない内容を、細かく機能分けして、アクティビティ図・シーケンス図・使用するライブラリ・言語などについて記したのが詳細設計書です。
詳細設計については以下の記事で詳しく解説しているので、併せてご覧ください。
【詳細設計書に盛り込む内容】
アクティビティ図・シーケンス図・IPO(処理機能記述)・データベース設計・ER図
など
関連記事:システム開発の詳細設計とは?役割や作成時のポイントも解説
開発は、詳細設計書の内容に従って、実際に技術者がプログラミングを行なう工程です。プログラミングを行なうなかで作成すべきドキュメントには、ソースコード納品があります。
ソースコードとは、ソフトウェア・システム構築時のプログラムを作る際に、そのプログラムに「どんな動作をさせたいか」という処理の内容を書いたテキストファイルのことです。
ソースコードの納品後は、クライアントが自分で運用を行うケースが多いため、ソースコードで納品する際は、コーディングや管理ツールなどの細かい設定を行いましょう。
ただし、ソースコードは成果物としてみなされない場合もあるため、著作権の取り扱いに関しては気を付ける必要があります。
テストは、単体テスト・結合テスト・総合テストの3つに大きく分かれています。
単体テストでは機能を一つずつ動かして確認し、結合テストではいくつかの機能を複合的に動かして確認し、総合テストではシステム全体の動作を確認します。
それぞれにおけるテスト項目をまとめたものがテスト仕様書で、その結果を記載したものがテスト報告書です。
【テスト仕様書/報告書に盛り込む内容】
テスト対象となる機能・テスト方法・テストの観点・結果 など
運用マニュアルは、完成したシステムをどのように動かし、運用するのかを記した手順書です。
開発作業を行なうのは開発会社なので、クライアントはシステムの使用方法を把握していません。クライアントの実際の業務を想定して、詳しい運用方法を共有することでスムーズな運用につながります。
【運用マニュアルに盛り込む内容】
業務の流れ・機能の操作方法・運用方法・セキュリティに関する情報(アクセス権・パスワードなど)・リカバリー/トラブルシューティングの手順 など
ドキュメントの作成時には、いくつか注意したいポイントがあります。ドキュメントのメリットを最大限活かすためにも、以下の点を意識することが大事です。
ドキュメントはクライアント・開発メンバー含め、不特定多数の人に共有するものです。そのため、基本的に誰にでも理解しやすい文章で書き、簡潔にまとめることが望ましいでしょう。
特に設計に関するドキュメントは、どうしても専門用語や技術的な内容の記載が多くなるため、難解な文章になりがちです。できるだけ読みやすくするには、ドキュメント全体でのフォーマット・記述ルールを決めておくことも有効といえます。
システム開発の途中で、一部が仕様変更になることも多々あるでしょう。このようなときにはドキュメントの改定も行なう必要がありますが、改定が遅れると実際の開発状況との乖離が生じてしまいます。
開発作業を行なうエンジニア・プログラマーと、他のメンバーとの間に認識のズレがあると、開発が一旦ストップしてしまうかもしれません。
不要な混乱を避けるためにも、仕様変更が生じればスピーディーにドキュメントの改定を行い、関係者全体に共有することが大事です。
システム開発が終わった時点で、ドキュメントが大量に出来上がっているケースもあります。しかし、ドキュメントはシステムの運用・保守・アップデートなどの際にも活用するため、大量にあっても適切に管理できなければあまり意味がありません。
作成後の活用シーンのことも考慮して、ドキュメントは必要以上に作成せず、管理しやすい状態にまとめておくとよいでしょう。
システム開発においてドキュメントは、おもに以下のような役割があります。
1.クライアントと開発会社のすり合わせのため
2.開発をスムーズに進めるため
3.システム完成後の保守・運用のため
ドキュメントにはさまざまな種類がありますが、実際に何をどのように作成するかは開発会社によっても異なります。発注者として、後で確認したい内容やドキュメントがあれば、要求定義などの段階で伝えておくとよいでしょう。
DeFactoryでは、システム開発の立ち上げ支援・各フェーズのフレームワーク活用法もサポートしています。その他、アイデア着想、ユーザーヒアリング、テストマーケティング、アジャイル・MVP開発と、システム開発における立ち上げ支援を全力サポートいたします。
また、経験豊富なエンジニアと事業開発経験者で、開発だけでなく事業設計から「一気通貫」した伴走を行います。 事業開発や立ち上げを検討しているご担当者様がいらっしゃいましたら、問い合わせページから資料請求や無料相談などお気軽にご連絡くださいませ。