これが解説書だ！

「解説書」は「暗黙知」を関係者で共有するためのドキュメント

ここでは、解説書のサンプルを2つ紹介します。
一つは、製品全体システムに関わる「システム概要」で、もうひとつは、あるモジュールにフォーカスした「制御設計書」です。

システム概要

下図にある「システム概要」は、ソフト・ハード・企画・品質保証など、さまざまな背景を持つ関係者が読み手になります。

そのため、ソフトウェア工学の範疇にある（例えばフローチャートやモデルなどの）アイテムにこだわらず、必要に応じてイラストやグラフなどの表現方法も活用し、読み手への情報の伝わりやすさを第一に考えて記述することが必要となります。

また、ユーザーズマニュアルに記載されているような、専門知識を持たない人でも理解できるレベルの内容から、内部の構造であるシステム構成までを、思考の過程を妨げないよう、関連付けを明確にしながら、段階的に詳細化・局所化していきます。

こうすることで、ソフトやハードの専門知識を持たない関係者に対しても、深い理解を促すことが可能となります。

制御設計書

下図にある「制御設計書」は、システムを構成する一部のモジュールを対象範囲とした「解説書」です。このドキュメントの想定読者は、そのモジュールの派生開発の担当者です。

一般的に、派生開発で引き継がれるのは、実際に動かすことのできるコードやモデル、そして機能仕様や要求一覧です。しかし、コードやモデルと機能仕様や要求一覧の間には大きなギャップがあります。

要求や機能は実現手段を選びません。その要求や機能に対して、制約やその他の理由により意思決定がなされ、多くの選択肢の中から一つの実現手段が選ばれます。それが、今のコードやモデルの構造となるのです。

しかし、従来の設計書では、その「意思決定がなされた根拠」がまるまる抜け落ちているのです。そのため、引き継いだコードやモデルを、品質よく保守していくには、かなりの「経験」と「想像力」を必要とします。

しかし、派生開発は新規開発に比べて"簡単"だと判断され、若手社員や外部社員に任すケースがほとんどです。そのため、ソフトウェアの品質は派生する度に悪くなり、いつの間にか手のつけられない状態になってしまうのです。

ここでは、実際に"架空のシステム"ではありますが、具体例を元に「解説書」を説明しました。これで、一般的な「設計書」と「解説書」の違いがご理解いただけたかと思います。

ところで、「解説書」に書かれている内容は、ドキュメント作成者が考え出したものではありません。それは、最初の開発の時に検討会の資料としてその都度つくられ、担当者のPCのHDDに残されたものであったり、検討会の中でホワイトボードに直接かかれた画像として残されたものであったり、ベテラン社員の頭の中にある暗黙知だったりします。その暗黙知を関係者の間で正しく共有することが、ソフトウェアひいては製品開発全体の生産性や品質の向上につながります。

既存資産の解説書に関する記事を見る

他のソリューションを見る

最新コラム