はじめに
こんにちは。カケハシの各プロダクトを支えるプラットフォームシステムの開発チームでテックリードを担当しているkosui(@kosui_me)です。
プロダクト開発の世界では、明瞭な社内向けドキュメントを書くための方法が数多く提案されてきました。読者の中には、製品要求を明瞭にするためにPRD (Product Requirements Document、製品要求仕様書) を書き、プロジェクトの背景から全体の設計やその代案について明瞭にするためにDesign Docsを書き、アーキテクチャに関する意思決定の記録を明瞭にするためにADR(Architecture Decision Record) を書いてきた方も数多くいらっしゃると思います。
しかし、どんな素晴らしいドキュメントも、何故か更新されなくなります。新メンバーへのオンボーディングのためにインフラ構成図を検索したあなたが見つけたのは、大規模なリノベーション前に記述された構成図かもしれません。過去にある機能が廃止された背景を検索したあなたは、きっと数年前のリリース当時の精巧な市場分析が書かれたPRDを見つけるでしょう。
つまり、どんな大規模でよく考慮されたソフトウェアも保守されなければ価値を毀損していくように、ドキュメントにも同じことが言えます。そして、ソフトウェアと同じように、ドキュメントもまた「価値を生む存在であると同時に、運用負荷も生む存在である」という側面を持っています。
では、どのようにドキュメントの運用負荷を下げれば良いのでしょうか？ 本記事では、ドキュメントを最新の状態に保つ負荷を極力下げつつ、なるべく最新の情報を手に入れることができる状態を目指すドキュメント運用手法を提案します。
対象となる読者
- 古い社内ドキュメントにばかり当たって困っている方
- 運用しやすいドキュメント構造に迷っている方
ストック情報を「リソース情報」と「イベント情報」に分類する
フロー情報とストック情報
情報を整理するための考え方として、フロー情報とストック情報という考え方が広く知られています。
フロー情報は、詳細な議事録やフィードバック、思考ログなど、情報の有効期限が短く、更新頻度が高い情報を指します。例えば、あるミーティングのアジェンダを参加者に共有した場合、そのミーティングの前後ではアジェンダは参加者にとって価値のある情報ですが、時間が経つにつれてその価値は失われていきます。
一方で、ストック情報は、PRDやDesign Docsなど、有効期限が長く、更新頻度の低い情報を指します。
リソース情報とイベント情報
筆者は、ストック情報をさらに二つに分類できることに着目しました。ストック情報の中にも、実は「ミュータブル(可変)な情報」と「イミュータブル(不変)な情報」の二つがあることがわかります。
例えば、あるプロジェクトにて、猫にどのような属性を持たせるべきかを検討したとします。プロジェクト発足当初、猫は「三角形の耳を持つ」と定義されていました。その後いくつかの変更を経て、最終的には猫ではなく「ねこ」と表記も変更されています。また、プロジェクトの途中段階で猫に「動物コード」を持たせることを検討しましたが、最終的には廃止されています。
この例では、「猫の属性」は時間の経過によって常に変化していく一方で、「ある日時に、属性を追加・変更・廃止した」という意思決定そのものは時間が経過しても不変であることが分かります。また、それぞれの意思決定には必ず「いつ合意したか」というタイムスタンプが存在することが分かります。そして、現在の猫の属性は、過去の猫の属性に関する意思決定の積み重ねによって表現できることが分かります。
ここで、ミュータブルな情報を「リソース情報」、イミュータブルな情報を「イベント情報」と呼び分けて考えてみましょう。
リソース情報
リソース情報は、プロダクトやシステムの現状を表現するミュータブルな情報であり、プロダクトやシステムの成長に合わせて常に変化していきます。例えば、システムの変化に応じて運用手順書は常にアップデートされていきます。つまり、あらゆる情報をリソース情報としてそのままドキュメント化してしまうと、それだけ多くのドキュメントを運用・保守する必要が発生します。
イベント情報
イベント情報は、あるプロダクトやシステムの意思決定に関するイミュータブルな情報です。その後、そのプロダクトやシステムがどのように変更されたとしても、その当時における意思決定そのものが遡及的に変更されるわけではありません。また、あるリソース情報に関するドキュメントを書く場合、イベント情報の積み重ねとして表現することで、書き手にとっての運用・保守のコストを低減し、読み手にとって過去の変遷をたどりやすくなります。
イミュータブルドキュメントモデル
つまり、ストック情報をドキュメントとして表現する場合、まずイベント情報をドキュメント化し、次にそれらのドキュメントを参照する形式でリソース情報をドキュメント化することで、下記のメリットを享受することができます。
- 読み手は、あるストック情報について、過去から現在に至るまでの変遷とその理由を辿ることができるようになる
- 書き手は、過去に書いたドキュメントのうち、リソース情報に関するドキュメントの鮮度だけを気にすればよい
ここで、この考え方およびこれを実践するためのドキュメント運用手法を「イミュータブルドキュメントモデル」と命名します。ちなみに、この命名や「エンティティをリソースとイベントに分ける」という考え方は、データモデリングの技法である「イミュータブルデータモデル」にインスパイアされています。なお、イミュータブルデータモデルについては「WEB+DB PRESS Vol.130｜技術評論社」内の特集「イミュータブルデータモデルで始める実践データモデリング」や「イミュータブルデータモデル - kawasima」にて非常に分かりやすく解説されています。
イミュータブルドキュメントモデルでは、各ドキュメントは次のような関係で表現できます。
イミュータブルドキュメントモデルでは、書き手は次の運用フローに従ってドキュメントを執筆します。つまり、書き手はストック情報をドキュメント化する場合、「ある決定の検討を開始した時」から「ある決定について合意した時」までの間、イベント情報のみをドキュメント化し、その決定について合意された時にリソース情報のドキュメントへ反映します。
さて、この運用フローを見た読者の方は「かなり重厚な運用フローだし、イベント情報だってドキュメント化するハードルは低くないよなあ…」と感じたのではないでしょうか。実際、PRDやDesign Docsは優れたドキュメント手法ではありますが、その実践は容易ではありません。そこで、筆者は次のような流れでイベント情報を書き上げていくことをおすすめします。
- 個別の意思決定ごとに、「承認された日」「背景」「決定されたこと」「決定による影響」のみをドキュメント化する
- より俯瞰的なドキュメントが必要だと感じたら(かつ、まだ力尽きていなければ)、それらをまとめてPRDやDesign Docsとしてドキュメント化する
これによって、ある程度は書き手の最初の一歩のハードルを低減することができますし、1.で力尽きたとしても過去の意思決定を理解するための糧を後世に残すことができます。ちなみに、「承認された日」「背景」「決定されたこと」「決定による影響」という四項目はADRを参考にしています。私たちのチームでは、この四項目が記載されたドキュメントをDecision Recordと呼んでいます。
まとめ
この記事では、まずストック情報に関するドキュメントの運用の難しさを示し、これを解決するためのドキュメント運用手法「イミュータブルドキュメントモデル」を提案しました。イミュータブルドキュメントモデルでは、ストック情報を可変な情報である「リソース情報」と不変な情報である「イベント情報」に分類することで、リソース情報のドキュメントはイベント情報の積み重ねとして表現できることに着目しました。
また、イミュータブルドキュメントモデルの実践方法として、まず小さな意思決定をイベント情報としてドキュメント化し、次にそれらの積み重ねを参照することでリソース情報やより抽象的なイベント情報をドキュメント化することを提案しました。この記事が少しでも皆様のドキュメント運用の負荷を低減するヒントになれば幸いです。
ここで、宣伝です。この記事に興味を持って下さった方には、ぜひ筆者が登壇するSmartHR様・リクルート様とのオンライン共催イベント「複雑化する開発体制におけるエンジニアの社内巻き込み術」(2023/10/24(火)19:00~)にもご注目いただきたいです。
共通認証基盤、共通決済基盤など、プロダクト開発チームの期待を満たさない共通〇〇基盤が何度も"刷新"されていく光景を目の当たりにした方は、きっと少なくないと思います。そこで私からは、共通基盤の必要性の提起から要件定義、開発、リリースまで、エンジニアが主導して共通基盤開発を成功させるためのプロセスを紹介します！
ぜひ、忘れないうちにお申し込みください。
