システム開発におけるドキュメントの重要性と短時間で書くコツ!

2022-11-162024-04-01

システム開発するうえで開発作業中の打合せや、不具合に対処するときなどにドキュメントは欠かせません。 そのため、ドキュメントの作成や管理を疎かにしていると、重要な局面で大きなトラブルが起きてしまう危険性もあります。

そこで今回の記事では、ドキュメントがシステム開発においてどのような役割を果たしているのか、実際にどのようなドキュメントにすればよいのかを具体的な種類も紹介しながら解説します。

システム開発におけるドキュメントの役割とは？

システム開発において、ドキュメントはどのような役割があるのでしょうか？主な役割は下記の3つです。

・発注者とシステム開発会社が円滑な意思疎通を図る

・スムーズな引き継ぎができるようにする

・不具合があったときに対処できる 

発注者とシステム開発会社が円滑な意思疎通を図る

システム開発はコーディングだけが仕事ではありません。コーディングの前に綿密なコミュニケーションを取って打ち合わせをします。

まず、発注者側が作成してほしい内容を開発会社に伝えて、どのように開発していくか、予算、納期はどのくらいか、どの程度の機能を実装できるのかを開発者側と発注者側で検討して、開発作業を詰めていきます。

何回も打ち合わせを重ねるので、ドキュメントに打ち合わせ内容を残しておく作業は大変重要です。完成したシステムが発注者の想定していたものと違っていた場合、トラブルに発展するケースがあります。言った言わない論争を防ぐためにもドキュメントは必須です。

また、開発作業は工程によって作業を分割して行う多重下請け構造になることが多く、階層が深いほど認識の相違を防ぐことが難しくなります。そこで、ドキュメントに各工程の詳細を記載することで、発注者と下請けの開発会社の間の認識の相違を埋められます。

システム開発は途中で仕様変更が発生することもあるため、バージョンごとに保存することで、変更履歴を残せるという役割もあります。

スムーズな引き継ぎができるようにする

下請け構造になっているシステム開発の現場では、要件定義がA社、設計がB社、実装・テストがC社、保守がD社といった作業工程ごとに請け負う会社が異なる場合があります。

1つのシステムを作り上げるにあたってドキュメントがなければ情報共有が困難になるため、仕様書は自然と必要になります。

また、システム開発は、開発して終わりではなく保守・運用といった作業が継続して必要です。退職や異動によって担当者が現場から離れてしまったり、別の会社に保守・運用を一任することもあります。

担当者が変わる際に、仕様書（ドキュメント）があれば、円滑な引き継ぎが可能になります。万が一システムに障害が発生した時にも仕様書をもとに早急に対処できるため、必ず用意しておきましょう。

不具合があったときに対処できる

システムに不具合が生じた際は、処理の流れをたどっていって、エラーを起こしている部分を特定します。

膨大な量のソースコードからエラーを発見して解消しなければならないため、複数の会社が入り混じって開発を行う際は、誰がどの部分を担当したのかがわかりづらく、不具合の解消まで時間がかかってしまいます。

そのような場合に役立つのがドキュメントです。機能ごとの仕様説明や担当者を明記しておくことで、不具合発生からの初動が早くなります。開発者の支援なしで不具合に対応できるようになると、業務への支障が出にくくなるため、ドキュメントは必ず残すべきです。

ドキュメントがないことにより起きるトラブルは？

基本的に中〜大規模のシステム開発はチームで行うものなので、自然とドキュメントの作成が必要になりますが、小規模のシステムの場合は、1人ですべて作成する場合があるため、ドキュメントを作らないケースも多々見受けられます。

しかし、いくら1人での作業とはいえ、下記のようなトラブルが発生する可能性があるため、注意が必要です。

・引き継ぎに時間がかかる

・引継ぎが正確でない

・不具合が発生した際のトラブル

・仕様変更があった際に記録できない

実際に1人で作り上げて運用してきたシステムでドキュメントを作成しなかった場合、その1人が永久にそのシステム運用に携われるのであれば問題は最小限なのかもしれません。ですが、突然の人事異動や運用会社の変更でその人の手元を離れてしまったことを考えてみましょう。

システムの使用をまとめたドキュメントを用意していなかったが為に、新しい担当者はソースコードを読み解いて、システムの全容を把握することに余計な時間を割かれてしまいます。正確な情報も無いので、無駄な工数が発生してしまうのは必然といえます。

1人で運用を任されていたとしてもドキュメントを作成する重要性はご理解いただけたと思います。

またそれ以外にも追加機能を実装する時など、何度も仕様変更が行われた際の変更履歴を残しておかなければ、先々で不具合が発生した時に解消が難しくなるということもしっかりと念頭に置いておきましょう。

システム開発におけるドキュメントの種類

システム開発は下記のような工程に分かれて作業を行います。

・要件定義

・外部設計（基本設計）

・内部設計（詳細設計）

・実装（コーディング）

・単体テスト

・機能テスト

・総合テスト

・保守運用

1つの会社が、1人の人間がすべてを請け負う場合もあれば、規模の大きいプロジェクトは複数人で請け負う場合もあります。そのため、各工程でドキュメントを用意するのが一般的です。主なドキュメントとしては、下記の8種類が挙げられます。

システム開発における主なドキュメントの一覧
提案依頼書	要件定義書	外部設計書	内部設計書
単体テスト仕様書	結合テスト仕様書	運用テスト仕様書	運用マニュアル

提案依頼書

提案依頼書とは、システムを作る目的や予算、システムの利用者といった、システムの概要をまとめたドキュメントです。英語でRFP（Request For Proposal）とも呼ばれます。

システム開発を外部委託する際に、発注側が作成する資料で、システムの抜け漏れや、不足している部分など、システムをより良いものにするための提案をもらうために作成します。

提案依頼書はシステムの開発のスタート地点であると同時に重要な工程です。ここで綿密にコミュニケーションを取れていないと、完成したシステムが想定外のものになってしまうため、知識と経験に基づいた記載が求められるドキュメントです。

要件定義書

要件定義書は、発注者側から提案されたシステムの全容や要望をもとに、予算・納期と照らし合わせてどのような機能を実装して、どこを捨てるか検討・記載するドキュメントです。

要件定義の作業も提案依頼書と同じく重要な工程なので、システム開発の経験を積んだエンジニアが担当することが多いです。なぜなら予算・納期に合わない機能実装を予定してしまうと、社内の人間だけでなく、発注者側、下請けの開発会社など、関わりをもつ人すべてに迷惑をかけることになるからです。

外部設計書（基本設計書）

外部設計書は、要件定義の内容をもとに、目に見える部分を設計・記載するドキュメントです。要件定義の段階では抽象的な部分が多いため、外部設計書を作成する中で具体的なすり合わせを行います。

発注者側とシステム開発会社の認識の相違を防ぐために、双方にとって見やすいドキュメントの作成が求められ、文字ベースの処理フロー以外に、画面のレイアウト、特定の処理を行った際にどの画面へ遷移するかを示した画面遷移図といったものも作成します。

つまり外部設計書は想定される業務内容の流れを図で表現することで、発注者側の意図が盛り込まれているのか、確認を行える最後のチャンスとも言えるでしょう。

内部設計書（詳細設計書）

外部設計書の内容をもとに、目に見えない部分を設計・記載するドキュメントです。主な仕様書としては、データベース設計図やER図、API設計図、バッチ処理設計といったものが挙げられます。

内部設計書は、エンジニア向けのドキュメントである為、発注者側のエンジニアがプロジェクトに参画している場合は、当然内部設計工程にも関わることとなります。

単体テスト仕様書

システム開発では3段階のテストを行います。機能ごとに行う単体テスト、複数の機能を組み合わせて行う結合テスト、テストデータを用いた運用テストの3つです。

不具合のない、正確な動作を保障するために3段階のテストを行います、

単体テストとは、機能ごとに行う動作テストです。まずは機能だけに絞ってテストの仕様書と結果をまとめた報告書を作成します。テスト仕様書はあらゆる不具合を想定して項目を設けなければなりません。

結合テスト仕様書

結合テストは、複数の機能を組み合わせて行うテストで、複数の処理が繋がった際に正常な処理が実行されるかを確認します。

運用テスト仕様書

運用テストとは、すべての機能を統合して、サンプルデータを用いて行うテストです。システムをリリースする前の最終確認になります。想定通りの挙動をしているかの確認はもちろん、遅延なくスムーズに処理が実行されるかどうかもチェックします。

運用マニュアル

システムは発注者が利用するものなので、運用のマニュアルを用意しなければなりません。業務の流れに沿って、システム開発会社が常駐せずとも一連の業務が行えるよう、説明書を用意しましょう。

ドキュメントを実際に書く際のポイントやコツとは？

システム開発と並行してドキュメントを用意するとなると、どうしてもそれなりの工数がかかってしまいます。開発者側のメイン作業はあくまでシステム開発なので、ドキュメントに割く時間は極力減らした方が作業時間は短く済みます。

しかし、誰が読んでも伝わるようなドキュメントにしなければならない点にも注意が必要です。ここでは、ドキュメントを短時間で書くポイント、コツを紹介するので、ぜひ参考にしてください。

なぜドキュメントを書くのか目的意識を持つ

それぞれのドキュメントを書く際、なぜそのドキュメントが必要なのかを明確にしていれば、自ずと記載する内容がわかるようになります。

何から書き始めればよいかわからない場合は、目的を意識して大枠を捉えましょう。外部設計書を作成するケースを例に挙げてみます。

外部設計フェーズで画面遷移図を書く際は、下記のようなことをイメージしながらドキュメントを書きます。

①システム開発を行う上で、処理ごとに適切な画面へ遷移することは正常な処理が行われている証拠であり、開発者側は達成感を得やすい。文でどの画面へ遷移するのかよりも、実際の遷移画面を簡潔に作成して図にした方が、開発がスムーズに進む。

②外部設計フェーズは、発注者側とシステム開発者側で認識の相違を解消するために、わかりやすい設計書が求められる。開発経験のない方が見てもわかるように、どの処理をしたらどの画面へ遷移するのか記載する。

③画面遷移図をあらかじめ作り込んでおくと、後のテスト段階が楽になる。テスト仕様書を書く際に、文でテスト項目を列挙するよりも、画面遷移図を参照しながらテスト項目を確認した方が作業効率が良い。

ドキュメントの読み手を意識する

作成するドキュメントには必ず読み手がいます。それは発注者側やシステム開発者側というサイドだけでなく、ベテラン、中堅、新入社員といったさまざまな属性を持ちます。重要なのは、読み手によって、記載する情報の粒度を調整することです。

たとえば、システム開発に関する知識のない発注者に向けて作成するドキュメントであれば、専門的な用語の使用は、文を縮められる分、かえって意味がわかりづらくなります。この場合は、専門用語を避けて書いたほうが伝わりやすいです。

一方、開発者同士で読み合うドキュメントであれば、専門用語の仕様は、冗長な文を縮められるのでおすすめです。また、設計とはまた違いますが、ソースコードに都度処理概要のコメントを残しておくと、後の保守・運用が非常に楽になります。

文だけでなく図表を使う

ドキュメントと聞くと文章を思い浮かべるかもしれませんが、意外と図表が多く使われるのがシステム開発におけるドキュメントです。むしろ、図表がないと見づらい場合もあります。

ドキュメントは誰が見ても伝わりやすい視認性が重要なので、冗長な文を連ねるよりも、図表で簡潔に記した方がわかりやすくなります。とくに条件分岐のフローは文章で表すよりも、表にまとめた方が確実に視認性が向上するため、図表にできる箇所は積極的に使用しましょう。

シンプルかつわかりやすい表記を心がける

ドキュメントは何よりもわかりやすさ重視で作成すべき資料です。どれだけ丁寧に記載されていても、文章が冗長である、視認性が悪いと、高い評価は得られません。なくても意味が伝わる言葉を削除する、一文あたり一つの意味といった点を意識しましょう。

開発者が把握している前提も記載する

新入社員が現場配属されて、いざドキュメントを見て作業をする時に、エンジニアとして知っていて当たり前のことがわからないケースが見受けられます。

暗黙の了解だったとしても、その現場に初めて来た方にとって不親切なドキュメントになるため、前提条件や、暗黙のルールなどをドキュメントに明文化しましょう。明文化しておくことで、既存の社員の中で認識の相違があった際に、すぐに対応できます。

失敗例・不採用となったケースも記載する

試した結果上手くいかなかった、検討した結果採用されなかったケースは、ドキュメントから削除せず、残しておきましょう。そのまま文章を残しておくのは正常な処理との差別化が難しくなるため、取り消し線を引くといった対応がおすすめです。

書いたドキュメントの管理方法

ドキュメントは作成後の管理が重要になってきます。せっかく作成しても見たいときにすぐファイルを開けないと作成した意味がありません。また仕様変更があった際にきちんとドキュメントを更新しなければならないため、ドキュメント管理には気を遣う必要があります。

ファイルが古く、ドキュメントの信頼性が低くなってしまうと、チームの皆がドキュメントを見なくなってしまいます。せっかく作成した仕様書が無駄になってしまうため、こまめに更新をかけるようにしましょう。

ドキュメントの管理を怠るとどうなるか

ドキュメントの管理を怠ると起こりうるケースをいくつか紹介します。

・同じ名前、似た名前のファイルが混在し、開きたいファイルがどこにあるかわからない

・どのファイルに何が書いてあるかわからない

・更新が止まっていて信頼性が低い

ファイル名は区別できて意味の通じるものを付ける

ドキュメントは共有のしやすさから、手書きではなくPCで作成されることが一般的です。ファイル名は一目見て内容がわかるものにしましょう。「外部設計書1」「外部設計2」といったように、適当に名前を付けてしまうと任意のキーワードでファイルを検索した時に引っ掛からなくなってしまいます。

またファイルだけでなく適切にフォルダ分けもするべきです。たとえば「2022年〇〇プロジェクト 外部設計書」というフォルダを作成して、その中に適切な名前のファイルを格納していけば一目で探したいファイルを見つけられます。検索したい時に使うキーワードを含めれば、検索にも引っ掛かりやすくなります。

また、似たようなファイル・フォルダ名は検索の際に作業効率を落としてしまうため、区別できるような名前の付け方をしましょう。プロジェクト名や年などを含めるのがおすすめです。

フォルダ管理をする際のルールについて詳しく知りたい方はフォルダ管理時のルールのコツやポイントを紹介している記事をご覧ください。

常に更新をかけてドキュメントを最新化する

システム開発は不具合の解消や追加機能があった際にシステムの仕様が変わります。仕様変更に合わせてドキュメントを更新して、常に最新のものにしないと、信頼性のないドキュメントになってしまいます。

仕様書通りに保守・運用していたものの、最新版ではなかったためにミスが生じる可能性があるため、必ず最新化するようにしましょう。

バージョン管理ツールが便利

ドキュメントの更新は新しいファイルを作成するのではなく、同じファイルを更新し続けるのが便利です。バージョンを復元・管理できるツールを使用することで、過去の変更内容を参照できるため、おすすめです。

よく使われるバージョン管理ツールとしては、Google Drive（グーグルドライブ）やGitHub（ギットハブ）といったツールがあります。

これらのツールを使えば過去の変更内容を参照、復元できるため、削除さえしなければいつでも任意のバージョンに戻すことができます。似たようなファイルの作成を防げる点もメリットです。

検索の手間を減らす方法

システム開発の際に用意されるドキュメントファイルは膨大な量があるため、とても人の手で探し当てることは困難です。そのような場合に支援してくれるのが検索機能になります。そこで、検索の手間を減らすことを意識しましょう。

主な対策としては下記の4つが挙げられます。

・ドキュメントは分割せずに、少ないファイル数で管理

・ドキュメントのファイルパスを記したドキュメントの一覧ページを作成する

・新しくドキュメントを作成する場合は、保存場所を共有しておく

・社内wikiツールを導入する

これらの対策をしておくと、どのフォルダに何が保存されているかわからない、探しているドキュメントがどこにも見つからないといったケースを防げます。

検索機能を持ち、ドキュメント管理をスムーズにする社内wikiツールに興味がある方はぜひおすすめの社内Wikiツールを紹介している記事をご覧ください。

まとめ

システム開発においてドキュメントの作成は、下記のような3つの役割を持ちます。

・発注者とシステム開発会社が円滑な意思疎通を図る

・スムーズな引き継ぎができるようにする

・不具合があったときに対処できる 

システム開発は、コーディング作業以外のコミュニケーション部分がプロジェクト成功の可否を握るため、非常に重要な書類です。

ドキュメントを作成する際は、何のために作るのか、読み手は誰なのかを意識しましょう。自ずと記載すべき内容がわかるようになります。ドキュメントの作成時はバージョン管理ツールを使って、過去の変更履歴を参照・復元できるようにしましょう。

また最後にドキュメント共有に役立ツール、GROWI.cloudを紹介して終わりたいと思います。