システム開発の際には、成果物としてドキュメントを作成することが一般的です。しかし、近年は細かくフィードバックを行いながら進めていくアジャイル開発も主流になりつつあるため、「ドキュメントは本当に必要なのか？」と疑問を抱く方もいらっしゃるのではないでしょうか。
私は、ドキュメントは重要な役割を果たすため必要だと考えます。なぜそう考えるのか、ドキュメントを残しておくことによるメリットを交えながら紹介していきます。
また、ドキュメントは存在しても活用されないと意味がないものです。活用されるドキュメントの書き方や、管理方法についても触れていきます。
この記事は、このような方に向けて書いています。
- ドキュメントがないとどうなるか知りたい
- システム開発で発生するドキュメントは、具体的などのようなものか知りたい
- ドキュメントを早く書くコツを知りたい
- ドキュメントをわかりやすく書くコツを知りたい
- ドキュメントの適切な管理方法を知りたい
システム開発のドキュメントに関するさまざまな疑問やお悩みを、解決できましたら幸いです。
実際の開発費用・期間をまとめた資料を無料で差し上げます。資料請求はこちら>>
システム開発におけるドキュメントとは？
ドキュメントという言葉は、一般的には書類や文章という意味で使われます。
システム開発の世界における「ドキュメント」は、システムの仕様書や設計書、使用方法をまとめた資料や説明書のことを指します。ソースコード内のコメントをドキュメントとして扱うこともあります。
実際の開発費用・期間をまとめた資料を無料で差し上げます。資料請求はこちら>>
ドキュメントが必要な理由
正直なところ、ドキュメントを作成するには手間と時間がかかります。また、発注者側でも、システムとマニュアルのみ納品されるならばそれでよいと考える方もいらっしゃいます。
では、なぜわざわざドキュメントを作成するのでしょうか。それは、少しでもずれの少ない意思疎通を行い、システム開発完了後の業務も円滑に行うためです。長期的にシステムを使うことを考えると、ドキュメントはとても重要な役割を持っています。
この項では、ドキュメントが必要な理由を詳しく解説します。
発注者とシステム開発会社が円滑な意思疎通を図るため
設計書や仕様書を残すことで、情報の共有漏れや認識のずれを極力減らすことができます。仕様を変更する時にも随時ドキュメントを更新して経緯を残すことができるため、言った・言わないのトラブルを防ぐことができます。
また、ドキュメントが残っているとシステムの状態を客観的に判断できる材料となります。納品物が要望通り出来上がったことを証明するためにもドキュメントは用いられます。
円滑に引き継ぎを行えるようにするため
システム開発後の保守・運用を別の担当者が行うことになったときも、ドキュメントがあれば円滑に引き継ぎを行うことができます。
もしシステムエラーや障害が発生した場合にも、そのシステムの仕様書があれば対処を素早く行うことができ、被害を最小限に抑えることができます。
ドキュメントがないことにより起きるトラブルは？
システム開発では、業務を進める上で必要なドキュメントを残すことが通常です。しかしエンジニアが1人体制の会社では、必要なドキュメントを全く残していないということが当たり前のように発生します。なぜかというと、1人体制なので他のチームメンバーと情報共有を行う必要が少なくともその時はないからです。
ドキュメントが残されていないと、システムの内容から見直す必要が出てきます。その結果、メンテナンスや運用の際に大きな障害になりえます。
極端な例ですが、その1人体制のエンジニアがいなくなった後にシステム障害が発生したとします。ドキュメントがないとシステムのソースコードを解析して、原因は何かを突き詰めるところから復旧作業を行わなくてはなりません。これは大きなタイムロスです。いつ復旧するのかわからないという、恐ろしい事態が起こることもありえます。
どんな業務や体制でも「自分以外の誰かがこの業務を引き継ぐ可能性がある」ことを視野に入れておく必要があります。だからこそ、ドキュメントを残しておくことは継続的なシステムの保守を行っていく上で重要です。
実際の開発費用・期間をまとめた資料を無料で差し上げます。資料請求はこちら>>
システム開発におけるドキュメントの種類
システム開発は、一般的には以下の流れで進んでいきます。
要件定義
基本設計（外部設計）
詳細設計（内部設計）
プログラミング
単体テスト
結合テスト
運用テスト
システム移行・運用開始
保守・運用
この項では、システム開発の段階ごとに発生する代表的なドキュメントを紹介します。
紹介するドキュメントは、すべてが必ずしも必要というわけではありません。それぞれのプロジェクトにおいて必要なドキュメントを選定して作成しましょう。
要件定義時のドキュメント
システムに関することのほとんどは、要件定義の段階で決定していきます。業務の流れ、データの流れを確認・決定しつつシステム化するものを決めていきます。詳しくはこちらの記事で解説しています。
提案依頼書（REP）
要件定義前の段階で、システム開発会社ではなく発注側が作成するドキュメントです。システムを作る目的など、開発したいシステム要件を明文化した資料です。提案依頼書についてはこちらの記事で詳しく解説しています。
要件定義書
発注者の要望（システム開発の背景・目的含む）をヒアリングした上で、何をシステム化して問題解決するか、何をシステム化しないかを明確にして記載します。
- システム概要
- 全体図
- システム要件……など
具体的には、システムを利用するアクター（システムを利用するユーザーの種類のこと。例えば「管理者」「会員」など）を定義し、アクターごとに求められる機能要件を記載します。
サーバー構成図
システムを設置するサーバーの構成を記載します。
業務フロー図
システムを導入した後の業務の流れについて、人の動きのシステムの動きを図式化した資料です。
基本設計時のドキュメント
要件を満たすために必要機能を洗い出して設計し、必要な画面の設計と、各画面の遷移の仕様を明確にする工程です。また、次の「詳細設計」に進むために業務ロジック（目的の処理をするために必要な顧客特有の仕様）を明確にしておきます。詳しくはこちらの記事で解説しています。
基本設計書
システムの「目に見える部分」の設計書です。具体的な画面のレイアウトや入出力するフォーマット、管理項目や実装したい機能などを、使う場面や運用の場面を想定しつつ設計します。
基本設計フェーズは、発注側がシステム開発工程に携われる最後のチャンスでもあります。アウトプットされた基本設計書に的確なフィードバックを与え、開発会社との認識の違いを極力なくしておく必要があります。
画面遷移図
画面遷移を図式化した資料です。例えば、会員登録フォームの入力画面に入力をすると登録確認画面に遷移し、確認が取れたら登録完了画面へと遷移するという図を作成します。
処理概要
初期表示するデータの取得仕様や、ボタンやリンクをクリックした際に行われるシステムの処理の概要を記載します。
項目定義書
データモデル（「顧客データ」「受注データ」など、システムで管理するデータのまとまりのこと）ごとにシステムに必要とされる項目を洗い出し、定義します。
具体的には、項目ごとの入力仕様（必須入力か否か、入力形式の制限、入力するデータの上限など）を定義します。またアクターによって表示する項目、非表示にする項目があるため、アクターごとにアクセスできる項目を定義し、記載したドキュメントです。
詳細設計時のドキュメント
具体的なプログラムの仕様を設計する工程です。この工程では主にシステム開発会社の開発者向けのドキュメントを作成します。
発注側にエンジニアが在籍していて運用は自社で行う場合は、この工程にも積極的に参加することが望ましいです。
詳細設計書
目に見えない、システム内部の設計書です。基本設計でできたシステムの大枠をもとに、プログラムの仕様書を作成します。
主な記載項目
- データベース設計、ER図（データをどのように整理して保管するか）
- コード定義設計
- API設計
- バッチ処理設計（定期的に自動処理されるものの処理概要）
- 外部システム連携設計
- プログラム一覧（プログラムのソースコード一覧）
単体テスト時のドキュメント
要件を満たしていることを保証するために、テストは重要な工程です。
単体テスト・結合テスト・運用テストを行ってバグを検出し、修正を繰り返すことで不具合の数を減らします。3つのテストについて、詳しくはこちらの記事で解説しています。
単体テスト仕様書・報告書
プログラムを単体で動かし、動作試験をするためにテスト項目を記載した仕様書と、そのテスト結果を記した報告書です。
結合テスト時のドキュメント
単体テストをクリアしたパーツ同士を合わせて、それらがきちんと動くかを確認します。機能間が連動して動作した場合に、仕様通りにシステムが動作するかを試験する工程です。
結合テスト仕様書・報告書
各プログラムをつなぎ合わせて1つの機能として正しく動作するか検証するためのテスト項目を記載した仕様書と、そのテスト結果を記した報告書です。
運用テスト時のドキュメント
システムのリリース前に実際の業務の流れに沿ってシステムを運用し、試験することを指します。仕様通りに出来上がっているかのチェックはもちろん、スムーズに運用をまわすための予行練習も兼ねています。
運用前に不具合を発見して修正できるように、思いつく限りの業務の全ケースのテストを行うことが理想です。
システムテスト（運用テスト）仕様書・報告書
システム運用開始前に実際の業務の流れに沿って試験し、正しく動作するか検証するためのテスト項目を記載した仕様書と、そのテスト結果を記した報告書です。
運用開始時のドキュメント
いよいよ運用開始です。発注者にシステムを納品し、実際に使用していただきます。
運用マニュアル
通常の運用業務の流れに沿って作成するマニュアルです。クライアントだけで一連の運用業務が行えるように、手順を記載します。
実際の開発費用・期間をまとめた資料を無料で差し上げます。資料請求はこちら>>
ドキュメント作成のコツ
ドキュメント作成は、わかりやすくスムーズに情報を伝えることが重要です。
しかし、ドキュメント作成に時間をかけるよりも、システムを作り込むことに時間をかけたいと思うのがエンジニアの常です。そこでこの項では、ドキュメント作りの時間を短縮しつつ、わかりやすい文章を書くコツをいくつか紹介します。
ドキュメントを書く目的を意識する
どのような目的でこのドキュメントが必要であるかが明確になっていれば、何をどのように書けばよいかがおのずとわかるはずです。例えば、詳細設計書を作成することになったとします。
①実際の開発を行うために必要な場合は、スムーズに開発ができるように詳細を事細かに書く必要があります。
②発注者へ成果物として渡す場合ならば、どのような処理を行っているのか、概要を書いたほうが伝わりやすいでしょう。
③保守運用の際に使う場合は、他の開発者がソースコードを読む際のガイドブックのような書類である方が使いやすいはずです。
このように、使われる目的に沿ってドキュメントを書くことはとても大事だと考えます。
読み手を意識する
誰が読むのか？を考えて書くことで、わかりやすい文章を書くことができます。
例えば、システムに詳しくない発注者に向けたドキュメントならば専門的な用語は避けて書いたほうが伝わりやすいでしょう。開発者同士ならば専門用語を使ったり、ソースコードにコメントを残しておいたりする方がわかりやすいこともあります。
ドキュメントの構成をイメージする
見出しを決めるなど、最初に全体の構成をイメージしてから書き始めることをおすすめします。構成をあらかじめ決めておくことで頭の整理がしやすくなり、スムーズに文章に書き起こすことができます。また、見出しがあることで何についての説明が書いてあるかがわかりやすく、読み手側にも伝わりやすいドキュメントを作ることができます。
シンプルにわかりやすくを心がける
文章量が多すぎると読み込むのに時間がかかります。また、どこに何が書かれているか探す手間が発生することもあります。
端的にまとめてあるドキュメントは、これらのデメリットを解消します。また、簡潔にまとめてある方が読みやすく、仕様を早く理解できるメリットがあります。
例えばドキュメントの文章でよくありがちなのが、1文に複数の意味が含まれていることです。「1つの分には1つの意味だけにする」「なくても意味が伝わる言葉は削除する」と意識すると、すっきりわかりやすい文章を書くことができます。
例
期待するシステム要件、非システム要件、保守、運用の要件をRFPに明記することで、各ベンダーから受けられる提案が同じ条件で記載した要件を前提としたものとなるので、提案の確度、粒度が揃い提案の比較検討がやりやすくなる。
↓
期待するシステム要件、非システム要件、保守、運用の要件をRFPに明記する。
これにより、各ベンダーから受けられる提案が同じ条件で記載した要件を前提としたものとなる。
結果、提案の確度と粒度が揃い、提案の比較検討がやりやすくなる。
↓
以下3点をRFPに明記することで、各ベンダーから同じ条件の提案を受けられる。提案の確度と粒度が揃い、比較検討がやりやすくなる。
・期待するシステム要件
・非システム要件
・保守、運用の要件
☆図や表を適宜利用し、文章を減らして理解しやすくまとめることもおすすめです。
暗黙知として理解されていることも記述する
担当者が変わることを考慮して、チーム内で大前提として共有されている事項も明文化しましょう。伝え漏れや認識のずれが少なくなり、より円滑に業務を進めることができます。
「このシステムではやらない」と決めたこともドキュメントに残しておく
システムで実施することをドキュメントに起こすことは当たり前ですが、「このシステムでやらない」と決定したこともできるだけドキュメントに残しておくと良いです。
やらないことをあらかじめ共有することで、考える手間や追加のコミュニケーションが減らせるため、他のやるべき作業に多く時間を使うことができます。
実際の開発費用・期間をまとめた資料を無料で差し上げます。資料請求はこちら>>
ドキュメントの管理方法
ドキュメント作成後の管理も、大切な仕事です。ドキュメントの信頼性が低いと、開発チームがドキュメントを見なくなってしまいます。例えば以下のようなトラブルはよく発生するため、注意したいところです。
- 同じ名前や同じような内容のドキュメントが複数存在し、どれが必要なドキュメントか分からない
- 必要なドキュメントが見つからない
- それらしきドキュメントを発見したはよいが、どこに何が書いているかすぐにわからない
- 適切に更新されず、最新版になっていない
ドキュメントを適切に管理し、トラブルを未然に防ぎましょう。
常に最新版を共有する
最新化されていないドキュメントがあると、コミュニケーションミスが起こりやすくなってしまいます。情報が更新されたときは、すみやかに最新版にするように心がけましょう。
都度新しいファイルを共有するのも良いですが、共有の手間を減らすためにバージョン管理ができるツールを選び、同じファイルを更新すると便利です。(バージョン管理ツールの例：Google Drive・GitHub・Swaggerなど）
バージョン管理ツールを利用する最大のメリットは、ファイル履歴を遡ることで1つ前、さらに前のバージョンがスムーズに見られることです。ツールを上手く活用することで、同じ名前や内容のドキュメントの乱立を防ぐことができます。
常に同じファイルを更新し、不要なものはアーカイブする
こちらも同じ名前や内容のドキュメントの乱立を防ぐ目的で行います。
例えば「要件定義書_1」「要件定義書_2」 「要件定義書_最終版」「要件定義書_最終版_fix」と同じようなファイルが複数存在していたら、ドキュメントを探している人は混乱してしまいます。
常に同じ1つのファイルを更新して、不要なドキュメントはアーカイブしましょう。
どこに何があるかを全員が理解し、見ればわかる状態にしておく
検索の手間を少しでも減らすために、どこにどのドキュメントがあるか、どのような内容が書いてあるか、一目でわかるようにしておきましょう。
例えば以下のような対策をすることで、検索の手間をぐっと減らせます。
- ドキュメントを複数に分けずに、少ないファイル数で管理する
- どこにどのようなドキュメントがあるか、ドキュメント一覧ページを作成する（社内Wikiを活用すると便利です）
- 新しくドキュメントが増える場合は、どこに格納するのが適切か確認する
これらの対策をすることにより、どこに何があるかわからない、探しているドキュメントが見つからないといったトラブルを防ぐことができます。
実際の開発費用・期間をまとめた資料を無料で差し上げます。資料請求はこちら>>
システム開発でドキュメントが必要な理由・まとめ
ドキュメント作成は大変ですが、発注側とのトラブル回避や長期間システムを安全に使うために重要な役割を果たします。継続的なシステムの保守を行うために、ドキュメントは常に最新版を残しておきましょう。
また、誰かに引き継ぎを行う可能性があることを常に念頭に置いて、シンプルかつわかりやすいドキュメントを制作することを心がけましょう。いつでもすぐに必要なドキュメントを探し出せるように、整理整頓した状態でドキュメントを管理しておくことも重要です。
整理をしやすくするためにも、むやみにドキュメントを増やすのではなく、本当に必要な事項のみを選定してドキュメントを作成しましょう。
この記事が、ドキュメント作成の手間を減らす手助けになりましたら嬉しいです。
最後に少しだけ、弊社アクシアのサービスを紹介させてください。アクシアでは他社で作成したシステムの保守を引き継ぐサービスを行っています。仕様書がなくてもご相談可能です。他の開発会社に断られてしまったものでも諦めず、ぜひ一度私たちにご相談ください。
