リソース情報
リソース情報は、プロダクトやシステムの現状を表現するミュータブルな情報であり、プロダクトやシステムの成長に合わせて常に変化していきます。例えば、システムの変化に応じて運用手順書は常にアップデートされていきます。つまり、あらゆる情報をリソース情報としてそのままドキュメント化してしまうと、それだけ多くのドキュメントを運用・保守する必要が発生します。
イベント情報
イベント情報は、あるプロダクトやシステムの意思決定に関するイミュータブルな情報です。その後、そのプロダクトやシステムがどのように変更されたとしても、その当時における意思決定そのものが遡及的に変更されるわけではありません。また、あるリソース情報に関するドキュメントを書く場合、イベント情報の積み重ねとして表現することで、書き手にとっての運用・保守のコストを低減し、読み手にとって過去の変遷をたどりやすくなります。
イミュータブルドキュメントモデル
つまり、ストック情報をドキュメントとして表現する場合、まずイベント情報をドキュメント化し、次にそれらのドキュメントを参照する形式でリソース情報をドキュメント化することで、下記のメリットを享受することができます。
- 読み手は、あるストック情報について、過去から現在に至るまでの変遷とその理由を辿ることができるようになる
- 書き手は、過去に書いたドキュメントのうち、リソース情報に関するドキュメントの鮮度だけを気にすればよい
ここで、この考え方およびこれを実践するためのドキュメント運用手法を「イミュータブルドキュメントモデル」と命名します。
イミュータブルドキュメントモデルでは、書き手は次の運用フローに従ってドキュメントを執筆します。つまり、書き手はストック情報をドキュメント化する場合、「ある決定の検討を開始した時」から「ある決定について合意した時」までの間、イベント情報のみをドキュメント化し、その決定について合意された時にリソース情報のドキュメントへ反映します。
さて、この運用フローを見た読者の方は「かなり重厚な運用フローだし、イベント情報だってドキュメント化するハードルは低くないよなあ…」と感じたのではないでしょうか。実際、PRDやDesign Docsは優れたドキュメント手法ではありますが、その実践は容易ではありません。そこで、筆者は次のような流れでイベント情報を書き上げていくことをおすすめします。
- 個別の意思決定ごとに、「承認された日」「背景」「決定されたこと」「決定による影響」のみをドキュメント化する
- より俯瞰的なドキュメントが必要だと感じたら(かつ、まだ力尽きていなければ)、それらをまとめてPRDやDesign Docsとしてドキュメント化する