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