システムのドキュメントを整備しよう | 青山システムコンサルティング株式会社

TEL:03-3513-7830|お問い合わせ

コラムカテゴリー:

システム開発では、開発段階、その後の運用段階において、様々なドキュメントが作成・活用されます。

例えば、

  • 設計書
  • テスト仕様書
  • テーブル定義書
  • 運用マニュアル

などです。

ところで、皆さんが関与されたシステムの運用・保守フェーズにおいて、必要なドキュメントが完全に揃っていることはありましたか?
私の場合は何らかのドキュメントが不足していることが大半でした。

また、ドキュメントは存在しているが、古いままで最新化されていないケースもありますね。
「ある機能の仕様を確認したくても、設計書が古く、結局プログラムを調べなくては本当のところは分からない」
という話もよく聞きます。

なぜドキュメントは揃わない?

なぜドキュメントは揃っていないのでしょうか。
また、なぜ更新されなくなってしまうのでしょうか。

以下の理由が考えられます。

  • プロジェクトの計画時点で検討・定義されていない、または予算優先、納期切迫などにより省かれてしまった。
  • 運用時に、担当者や更新ルールが不明確で、更新が行われなくなった。
  • 担当者変更の際にきちんと引き継がれなかった。
  • 忙しさにかまけて更新されなくなった。

ドキュメント整備は失敗しがち

ドキュメントが無かったり不正確であることは、作業効率の低下や、バグ・障害の原因になります。
そのため、多くのプロジェクトでは、
「ドキュメントを最新化しよう!」
「無いドキュメントを整備しよう!」
という掛け声が上がります。
しかし、それらは軌道に乗らなかったり、途中で挫折することも少なくありません。

経営層などの上層部含め課題と認識し、ドキュメント整備に予算・人が投入されればよいのですが、残念ながらそのようになることは少ないです。
システム自体の開発と異なり、ドキュメント整備だけでは新たな付加価値を生むとは見なされないからです。

システムの大きな改修や刷新に乗じて、ドキュメント整備を盛り込むという場合もあるでしょう。
しかし大抵の場合、ドキュメント整備は、現場の要員が忙しい時間の隙間をみて取り組むことがほとんどです。

そのようなわけで、ドキュメント整備にはある程度時間がかかります。
そして途中でメンバーの入れ替わりや急ぎのシステム改修などが入り、ドキュメント整備は忘れ去られて行ってしまうのです。

ではどのように取り組めばよいのか?

ドキュメント整備は一日にして成らず。上記の通り期間を必要とする場合がほとんどです。
途中で挫折しないようにするために、最初にしっかりとロードマップを描きましょう。

何段階かのステップを設け、都度成果が上がるようにしていきます。
そのようにすれば、途中で中断があっても、リスタートしやすくなります。

ステップ1 一覧による現状把握

まずはドキュメント一覧を作成し、どのようなドキュメントがあり、それらが最新化されているかを明確にしましょう。

ドキュメントが揃っていないプロジェクトでは、一覧がないか、あっても古い場合が多いです。
まずは現状を正確に把握しましょう。

<ここでわかること>

  • 存在するドキュメントと、その最新化有無

ステップ2 対象ドキュメント選定

一覧化できたら、以下①②を決めましょう。

①存在するドキュメントについて、今後も使用・更新し続けるかどうかを決める。

ドキュメントを維持するにもコストがかかります。
今あるドキュメントはそのコストに見合ったものでしょうか?
利用価値の低いものは切り捨てることも検討しましょう。

<切り捨てる候補>

  • ほとんど使われていないもの
  • 他で代替できる/二重管理されているもの

②新たに整備するドキュメントを決める。

今は存在しないが、新たに作るものを決めましょう。
優先して作るべきなのは、以下のような課題に対応するためのドキュメントです。

<課題>

  • システム調査に多くの時間を費やしている。(毎回同じようなことを調べている)
  • 品質が悪く、バグや障害の多い機能がある。
  • よく行われる作業について、手順書がない。
  • 属人化している知識/手順がある。

無理やり新たなドキュメントを作る必要はありません。
このような課題の解決につながるドキュメントを整備しましょう。

また、システムの全機能について、一律に設計書を揃える必然性はありません。
上記の課題を抱えている個所について、優先的・重点的に整備しましょう。

ステップ3 担当者、更新ルール決定

維持するドキュメント/追加するドキュメントが決まったら、まずその更新担当者を明確にしましょう。
また、そのドキュメントを更新するトリガー(きっかけ)を明確にしましょう。

例:

CRUD図(データベースのテーブルを、どのアプリケーションが参照・更新するかを表すマトリクス表)

  • 更新担当者:機能の設計担当者
  • 更新確認者:機能の設計レビュアー
  • 更新トリガー:新規機能の設計時、既存の機能変更時/削除時

ステップ4 最新化と作成

さてここまで来ましたら、ドキュメントの最新化と作成を進めましょう。
システム開発同様にドキュメント毎にWBSを引いて取り組みます。

上記の通り、隙間時間を使って行うことが多いので、中長期的なスケジュールになることもあります。
途中で中断することもあるでしょう。
担当者の自助努力だけでは、挫折してしまうこともあり得ます。

ワーキンググループを設置し、定期的に状況確認を行いましょう。
スケジュール通り進まないこともありますが、スケジュールを調整し、粘り強く取り組んでください。

終わりに

私自身、多くのプロジェクトでドキュメントの問題に直面・関与してきました。
そこで、これまでに経験してきたこと、取り組んできたことを改めて整理してみました。
このコラムが同じような問題に取り組む皆さんの一助となれば、幸いです。

 

関連サービス

この投稿をシェア

2023年09月11日 (月)

青山システムコンサルティング株式会社

山口 晃司