開発にはドキュメントが必要と聞いたことはあっても、どのようなものか分からないという方はいるのではないでしょうか。

ドキュメントには、要件定義書、基本設計書、詳細設計書など多くの種類があり、システム開発に関わる人達のコミュニケーションツールや情報を共有する手段として使用されます。

度重なるシステム改修などで、最新化されていないドキュメント類があると、コミュニケーションミスが起こりやすく、引き継ぎや、システム変更などに時間がかかってしまいます。

そうならないために、ドキュメントの意味や使い方、改定が必要なケースを正しく理解することが大切です。この記事では、ドキュメントの意味と種類、ドキュメントが必要な理由をはじめ、運用するポイントやメリット・デメリット、アウトソーシングする際の注意点についてご紹介します。

開発におけるドキュメントの意味と種類

一般的にドキュメントと言うと、書類や文章という意味ですが、システム開発では、システムの仕様書や使用方法をまとめた資料や説明書のことを指します。

開発のドキュメントの種類には、「要件定義書」「詳細設計書」「運用マニュアル」などがあり、これらの文章はシステムを開発する工程ごとに必要です。それでは、各開発工程に必要なドキュメントの種類と概要をみていきましょう。

各開発工程で作成されるドキュメントの種類

システム開発は、クライアントと対話をし、どのようなシステムを構築するのかを定義する要件定義から始まり、実際にプログラムを構築し、テストを行い、納品するという手順を踏みます。

■要件定義書
クライアントと対話をし、どのようなシステムを構築していくのかを決めていく際に作成される書類です。求められるシステムの要件や構築する目的、おおまかな予算などをクライアントと取り決めするために必要となります。

■基本設計書
要件定義から、具体的な画面のレイアウトや機能を設定した文書です。実際に運用されるシーンを想定して作成します。

■詳細設計書
基本設計書で大枠の機能を記載した内容を、実際にプログラムに落とすことを想定して、細かく機能分けした文書です。

■単体テスト仕様書
プログラムを一つ一つ動かし、動作に問題がないことを確認するために入力値と出力値を記入したテスト項目を記載します。

■結合テスト仕様書
複数のプログラムをつないで、一つの機能として問題なく動作するかを確認するためにテスト項目をまとめます。

■システムテスト仕様書
システム全体をつないだときに、想定される動作をするかを確認するためのテスト項目がまとめられた文書です。

■運用マニュアル
クライアントに使用方法を教えるための手順書となります。

このように、ひとつひとつの工程を積み重ねてシステムは構築されるのです。開発の各工程ごとに書類があるので、システム開発終了後には、かなり多くの仕様書ができあがります。
一部の方は、システムそのものと、マニュアルだけ納品されればよいと考える方もいますが、長期的にシステムを使うことを考えるとドキュメントはとても重要です。

ドキュメントが必要な理由

ドキュメントが必要なシーンは大きく分けて、クライアントとコミュニケーションを取るときや開発工程で担当者が変わるとき、保守・運用するときの3つがあげられます。なぜ、このようなドキュメントが必要となるのかその理由を見ていきましょう。

クライアントとのコミュニケーションに

ドキュメントを作成し共有することで、クライアントの意思疎通を図り、円滑な情報共有とコミュニケーションを行うことが可能です。開発を開始する前にクライアントと開発者で、予算やシステムを作る目的、システムを構築するための一つひとつの工程におけるスケジュールや担当者の割り振りなどを明確に文書に残しておきます。

文書に残すことで、言った言わないなどのトラブルを防ぐことにもなり、変更時も随時更新していくことで経緯を残すことができるようになるでしょう。

工程をまたぐとき

多くの開発現場において、最初から最後まで一人の担当者もしくはリーダーが実際のシステム作成を行うことはほぼありません。設計や構築、テストや検証など開発のフェーズにあわせて、もっとも適した人材が担当者となり、それぞれの役割を果たすことが求められています。

もちろん、プロジェクトマネージャーのようにプロジェクト全体を俯瞰し工程間の折衝を行う役割を持った人もいますが、工程をまたぐときに引継ぎが円滑に行えるようドキュメントをしっかりと作る必要があります。

保守・運用するときに

システムは構築・運用して初めて意味をなします。しかし、長く運用を続けていくうちに、担当者が退職したり、変更になったりすることも考えられるでしょう。その際、システムの構築からテスト、運用までの一連の流れや経緯をドキュメントとして残すことで、全体の流れを把握し、業務を引き継ぐことが容易になります。

もし、ドキュメントが残されていない場合は、システムの内容から見直す必要が出てくるため、メンテナンスや運用の大きな障害となるでしょう。

ドキュメントの整備・改定

各開発工程でのコミュニケーションや運用を行う上で大切な役割を果たすドキュメントですが、システムに変更を加えた場合、改定する必要が出てきます。改定が必要なケースを確認していきましょう。

開発中に仕様が変更になるケース

開発を進めていくと企画段階ではわからなかった問題やトラブルが起こり、システムの仕様や開発スケジュールの見直しを迫られる場合があります。計画の見直しが必要になった場合は、ドキュメントの改定が必要です。変更になった経緯を含めて記載しておくことで、どのように開発が進められたか確認できるようになります。

運用開始後の修正

システムを運用していく中で、機能の追加や改善を求められることもあるでしょう。そういった際にプログラムの修正を行う場合は、ドキュメントの改定も必要です。また、障害発生時の緊急対応の際にドキュメントの改定が必要なケースもあります。

アップグレードに伴う修正

システムを作成した後も、ハードウェアの改定や、ソフトウェアがアップグレードされた際には、その変更に合わせて、システムも変更が必要になります。それに伴いドキュメントを改定する必要がでてくるでしょう。

ドキュメント作成のメリット

ドキュメントを作成するには手間や時間がかかる上、作成後も必要に応じて改定を続ける必要があります。しかし、ドキュメントの作成には様々なメリットがあるため、手間がかかっても準備をするべきでしょう。ドキュメントを運用するメリットについて見ていきましょう。

コミュニケーションミスを防げる

システム開発には、クライアントや営業担当、各工程の開発者など多くの人が関わってきます。システムの処理内容などは複雑で多岐にわたるため、口頭では伝えきれないことが多く、ドキュメントなどを作成し文書によって情報を共有する必要があります。各工程でドキュメントを作成し文書で合意を行うことで、コミュニケーションミスの防止に繋がるでしょう。

不具合があったときに対処がしやすい

システムを動作させていくと通常のケースは動作するが、一部のケースだけ動かないといったトラブルが生じることもあるでしょう。そういったことが起こった際には、ソースコードを見る必要があるためドキュメントがないと大変な手間なります。一つのエラーを直すのに大変な労力を要することもあるのです。

運用時に役立つ

ドキュメントの一つとしてユーザーマニュアルを作成すれば、使い方がユーザーにもわかりやすくなります。ユーザーと正しい操作方法を共有することで、不具合が起こりにくくするとともに操作方法のお問い合わせを減らすことが可能です。丁寧なマニュアルはユーザーの安心感にも繋がり、顧客満足度を向上させるのにも役立つでしょう。

ドキュメント作成のデメリット

先ほども少し触れましたが、ドキュメントを作成するデメリットの一つに手間と時間がかかることがあげられます。具体的に、作成や改定における課題について確認しておきましょう。  

わかりやすい文章を書くのが難しい

誰にでもわかりやすいドキュメントを作成するには、文章を書くスキルが必要です。しかし、開発に関わる技術者が文章を書くことが得意とは限りませんし、技術的な専門用語を多用するため、内容がつかみにくくなる恐れがあります。また、案件ごとや作業工程ごとに異なったフォーマットを使用していたり、記述内容が統一されていなかったりすることもあります。読みやすいドキュメント作成には、フォーマットの整備・統一や記述するスキルが必要となるでしょう。

改定する際に変更箇所が多くなる

各工程ごとにドキュメントが作成されるため、変更を行った際に修正すべきドキュメントが複数にまたがる場合も考えられます。修正漏れが無いように留意するのはもちろんですが、各工程の担当者にも情報共有を行うことが必要です。また、最新版のドキュメントの管理や共有も大切になってきます。ドキュメントの新旧が入り混じってしまえば、混乱のもとになりかねません。

改定が間に合わず現状とずれてしまう

過密スケジュールの中で開発が進むことも多く、システムのリリースをするための実際の業務を優先させ、ドキュメントの改定が後回しにされることもあります。特にリリース直後はシステムの不具合の解消や改善などが優先され、ますますドキュメントの整備は遅れます。そのため、システム運用の実情とドキュメントの乖離が起こることもあり、ドキュメントを作る意義が失われてしまいます。実情と離れてしまったドキュメントを誰も信用しなくなるうえ、万が一事情を知っている担当者がいなくなってしまえば、開発の経緯やシステムが抱える問題点などは全てわからなくなってしまうでしょう。

アウトソースする際の注意点

ドキュメントの作成には数多くのメリットがありますが、作成や管理にかかる手間や時間が問題となります。アウトソーシングを活用することで、ドキュメントの作成・管理にかかる自社の負担を減らすことが可能です。アウトソーシングする際に注意するべき点を見ていきましょう。

アウトソーシング先の得意分野の確認

それぞれの会社で得意な分野が異なるため、自社が所有しているシステムがアウトソーシング先の会社で対応可能かどうかの確認が必要です。チェックポイントとして、業務知識の有無、対応可能な使用言語、アウトソーサーとしての実績などがあげられます。依頼前に十分確認しておきましょう。

セキュリティ

システムに触れるということは、自社システムの構成がわかってしまうため、システムの弱い部分もわかってしまいます。また、個人情報にも触れる可能性があることから、セキュリティに対して意識の高い会社であるかは、とても大切です。

サービスの内容

アウトソーシングサービスの内容は、各社で違いがあります。

度重なる修正で、ドキュメントがアップデートされていない場合は、既存のソースを解析し、必要なドキュメントを作成するサービスがおすすめです。

今後もプログラムの修正が頻繁にある場合は、プログラムを修正すると自動で仕様書も変更されるツールを利用すると良いでしょう。ドキュメントの改定自体が不要になり、本業に力を注ぐことができます。

また、顧客からのお問い合わせを減らしたい場合は、ユーザーマニュアルやFAQのみ改定を取り扱っている会社がおすすめです。さまざまなサービスがあるので、自社の状況や予算にあわせて使い分けると良いでしょう。

まとめ

ドキュメントは各開発工程や運用をスムーズに進め、認識のすり合わせを行い、経緯を記録するために大切な役割を果たします。理想としてはシステムとドキュメントの差異がないようにするべきですが、実際には開発中の手戻りや緊急対処のために、ドキュメントの改定に手が回らないこともあるでしょう。

アウトソーシングのサービスを利用することで、ドキュメント改定の手間が省け、コアビジネスに力を注ぐことができます。システムの運用をスムーズに進めるためにも、一度アウトソーシングサービスの利用を検討してみてはいかがでしょうか。

記事についてのご質問

この記事について、あなたの「もっと知りたい！」にお答えします