ドキュメント作成の重要性と品質について

これまで運用保守で使用するドキュメントや、基本・詳細設計など

プロジェクト内で利用するドキュメントを作成してきた経験から、

ドキュメント作成の考え方や構成のポイントについて記載したいと思います。


ドキュメントがなぜ大事か

「エンジニアという職種でドキュメントって大事なの？」と疑問に思う方もいるかもしれません。

私自身の経験でも 「ドキュメントが残っていないことで苦労した」 という場面は少なくありませんでした。

ドキュメントが大事な理由は、以下の3つに集約されます。

1. 属人化を防ぐ
担当者が異動した、休んだ、退職したなど

それだけで作業が止まってしまうことは、業務では頻繁に発生します。

業務では複数人のチームで作業を担っているにもかかわらず、担当者しか作業内容がわからないという状況は、品質という観点でも望ましくありません。

ドキュメントが整備されていれば「誰がやっても同じ結果が得られる」状態、言い換えれば一定の品質を保つことができます。

2. 仕様・構成の見える化ができる
1とも関連しますが、記憶や口頭伝達に頼っていると、仕様や構成がどんどんブラックボックス化してしまいます。
ドキュメントに残しておくことで、時間が経っても正確に内容を確認できます。

また、仕様や構成をドキュメント化しておくことで、有識者にレビューしてもらい、構築前に問題がないかを確認・修正することもできます。


3.認識合わせができる
チームメンバー間、もしくは他チームとの認識ずれは、後々のトラブルの元です。

ドキュメントに記載しておけば、それをもとに全員が同じ前提で作業を進めることができます。

ではどういったドキュメントがよいか

ドキュメント管理のポイントは様々な観点はあると思うが

私自身の経験から以下の観点は最低限必要だと考えています。

1. わかりやすいフォルダ階層・ファイル名

ドキュメントの中身ではないですが、非常に重要なポイントです。

「ドキュメント階層がわかりにくく、目的のファイルにたどり着けない」

また「ファイル名が適切でないため、知りたい情報が書いてある資料だと気づけない」

このような事態は現場で何度も経験してきました。

そのため「設計書」「手順書」「課題表」など、誰が見ても分かるようなフォルダ階層を意識することが重要です。

ファイル名についても「中身にどんな情報が記載されているかがひと目でわかる」ことを意識して作成する必要があります。

2. 定期的な更新

一定のイベント時（例えば構築完了後、アプリ担当者への引き渡し後、運用への引き渡し前など）に、

古い情報となっていないかをチェック・更新することも重要です。

実際の現場では、設計当初に決めた運用設計と、現在想定されている運用設計が全く別物になっている というケースは珍しくありません。

また、ドキュメントの更新履歴を残すことも大切です。

これにより「なぜ変更されたのか」「誰が変更したのか」がわかり、認識齟齬を防ぐことができます。

3. 図や表の利用

ドキュメント作成時には、文章だけでは伝わりにくいことが多くあります。

例えば システム構成図やネットワーク構成図などは、「どこからどこに接続されているか」を視覚的に表現しないと第三者と認識を合わせることができません。

また、サーバやソフトウェアの一覧などが必要な場合は、表形式で整理することで、さらにわかりやすくなります。

まとめ
ドキュメント管理がなぜ大事かまた現場で最低限重要なポイントについて

記載しました。

インフラエンジニアにとって 「ドキュメント作成＝インフラシステムの品質」 と
言っても過言ではありません。自分のため、チームのため、将来の誰かのために
私も今後「誰が読んでも理解できる、迷わず動ける」 ドキュメント作成をしていきたいと
考えています。