エンジニアと言えば、PCに向かいコードを書いたりサーバの監視を行うなど、専門的な業務を行っているイメージを持つ人が多いでしょう。
一方で、Webサービスやシステムの開発・運用を進めるにあたり、必要なドキュメントが多く存在します。そして、それらを作成することもエンジニアの大きな仕事のひとつです。
ここでは、開発や運用業務の中で必要となるドキュメントの種類と、求められるドキュメント作成スキルについて解説していきます。
開発におけるドキュメントの種類
はじめに、システムの開発や運用を進める上で、プロジェクトの段階ごとで発生する代表的なドキュメントを紹介します。
ここで紹介するドキュメントが必ずしも必要というわけではなく、それぞれのプロジェクトに合わせて必要なものを選定して作成していくものとなります。
これからIT業界を目指す人にとっては慣れない用語かもしれませんが、各ドキュメントの役割と特徴を押させていきましょう。
要件定義書
クライアントの要求をヒアリングし、その要求をシステム要件へ機能へ変換していくことを要件定義といいます。
そして、その要件定義で定められたシステムの全体像や細かい機能までをまとめてあるドキュメントが「要件定義書」にあたります。
具体的には、システムの概要、業務フロー、システムに必要な機能、セキュリティ関連、そして開発の計画などが纏められます。
要件定義書の内容は、開発中や運用開始後におけるすべての基盤となる重要なドキュメントといえます。
外部設計書
「外部設計書」は、要件定義の内容をもとに、目に見える部分の設計について記載されてあるドキュメントとなります。
要件定義の段階では抽象的な部分が多く、外部設計書を作成する中でより具体的なすり合わせを行います。
そして、処理のフローから、画面のレイアウト、ある処理を行った際にどの画面へ遷移するかを示した画面遷移図などを作成します。
内部設計書
「内部設計書」は、外部設計書の内容をもとに、システム内部の動作や機能など目に見えない部分の設計について記載されているドキュメントです。
具体的な内容としては、データベースの設計図、API設計図、バッチ処理設計、ER図といったものが挙げられます。
実際のプログラミングの工程に入った時に、プログラマーがどの機能をどのように実装していけばいいかを具体的に定めた指示書のようなイメージとなります。
テスト仕様書
開発されたシステムが、要件を満たしていることを保証するためにテストが行われます。
テストでは、実際にプログラムが正常に動くかを確認していきます。
その際に使用する、動作確認をするためにテスト項目を記載した仕様書のことを「テスト仕様書」といいます。
運用マニュアル
テストが問題なく完了しシステムが完成すると、発注者にシステムを納品し実際に使用していただきます。
納品後に、クライアントだけで一連の運用業務が行えるように手順を記載したものを「運用マニュアル」といいます。
なぜ、ドキュメントが重要？
ここまでで紹介してきたように、システムの開発や運用においては複数のドキュメントがあり、さらに作成するには手間と時間がかかります。
一方で、ドキュメントを作成することで、発注者と開発者で共通の認識を確認し合うことができ、開発中そして開発完了後の業務も円滑に行うことができます。そのため、ドキュメントはとても重要な役割を担っています。
ここでは、さらに詳しくドキュメントが必要な理由を解説していきます。
共通認識を持つため
基本設計書や仕様書を残すことで、発注者と開発者の間で、情報の共有漏れや共通認識のずれを減らすことができます。
仕様を変更する際にも随時ドキュメントを更新して経緯や記録を残すことができるため、どちらかが言った・言わないのトラブルなどを防ぐことができます。
長期的な運用の実現のため
システム開発後の保守・運用を別の担当者が行うことになったときも、仕様書や運用マニュアルなどのドキュメントがあれば、円滑に引き継ぎを行うことができます。
また、システムエラーや障害が発生した場合にも、そのシステムの仕様書があれば対処を素早く行うことができ、長期的な安全な運用を可能とします。
どんなドキュメント作成スキルが必要？
ドキュメントの種類と重要性を理解した上で、それらを作成するには、どういったスキルや視点が必要かを解説していきます。
ドキュメントの構成を考える力
エンジニアは、物事を構造的に捉える力が求められます。
具体的には、全体を把握した上で構成要素に分解していくことを指します。
そうすることで、構成をあらかじめ決めておくことができて、頭の整理がしやすくスムーズに文章に書き起こすことができます。
また、読み手にとっても伝わりやすいドキュメントを作ることができます。
読み手と目的の明確化
あらゆるドキュメントがあることから、そのドキュメントが「誰に向けて」「何のために使われるのか」を意識して作成する必要があります。
例として、システムについて詳しくない発注者に向けたドキュメントであれば、専門的な用語を噛み砕いて書いたほうが分かりやすいでしょう。
見る人が、クライアントかプロジェクトメンバーか、知識を持っているか持っていないか、どのように活用するかなどを考え、ターゲットとその目的で情報を整理します。
相手と目的で絞り込んだ情報を使ってドキュメントを作成することで、分かりやすさが格段に上がります。
全体的に見やすくする
文章の内容も重要ですが、一目で分かりやすいドキュメントにするよう意識することも必要です。
具体的には、下記のことを意識して作成すると全体的に見やすいドキュメントとなるでしょう。
・画像を多く使用する。
・フローや図を取り入れる。
・見出しや箇条書きを用いる。
まとめ
開発運用で必要となるドキュメントの種類と求められるドキュメント作成スキルについて、解説してきました。
未経験エンジニアとなると、要件定義書や設計書のような上流工程が担当するものではなく、運用マニュアルや報告書を作成する機会が多いでしょう。
ドキュメントの種類が違えど、分かりやすいドキュメントを作成するために必要なスキルや考え方は共通です。
まずは、すぐに意識できることから始めていきましょう。
