こんにちは。ノバセルのデータプロダクトチームにて開発エンジニアをやっている山中（yamnaku_）です。 現在は、ノバセルの各種分析システムのバックエンド開発を行なっています。 特に、データウェアハウス製品Snowflakeを利用したデータ基盤の開発・運用に取り組んでいます。
私の所属するチームでは、意思決定を記録するドキュメントとして、Architectural Decision Record（ADR）の運用を始めて3ヶ月ほどが経ちました。 今回は、感じることが出来た効果についてご紹介したいと思います。
背景と課題
ひとつ目のプロダクトである「ノバセルアナリティクス」のローンチから3年が経ち、ノバセルでは様々なシステムが現在稼働しています。 ノバセルはお客様のデータや、検索量といったサードパーティデータをTVCM放映データと掛け合わせて分析を行っています。 そのようなサービスの特性上、モノリシックなシステムが鎮座する形ではなく、小規模なシステムやバッチが多く運用される状況になっています。 特に、以下のような3つのカテゴリに分類されるシステムが多く存在します。
- データを収集するバッチシステム
- データを統合し、分析するバッチシステム
- 分析結果をユーザーが参照・検索できるアプリケーションシステム
そうした中で、各システムのアーキテクチャ意思決定の過程については、ドキュメンテーションが不足していたり、ドキュメントの置き場所が指定されていないことにより散在していました。 特に、以下のようなコードを読んでも分からない点については、ドキュメントによって補う必要がありました。
- どういった選択肢を検討し、なぜそのアーキテクチャを選択したのか
- 意思決定の背景にあったビジネス上の事情や顧客の要求
また、メンバーからは「（チームや組織としての）意思決定の流れが見えにくい」という意見ももらっていました。 こうした項目について、共通のドキュメントフォーマットを定め、置き場所を明示することにより、以下のような効果を期待しました。
- アーキテクチャ選定の意思決定プロセスをフォーマット化し、より早くより良い意思決定を助けること
- チーム体制の変更や、新メンバーが加入した際に、スムーズにシステムの理解が進むこと
- 意思決定のフローを透明化し、状況の把握をしやすくしたり、納得感を醸成すること
採用したフォーマット
ドキュメントの運用方法や、フォーマットの策定にあたっては、『Googleのソフトウェアエンジニアリング』の第10章「ドキュメンテーション」を参考にしました。 初期はDesign Documentを参考にしながら以下のような項目を最終的に採用しました。
ドキュメントオーナーと変更履歴
ドキュメントはメンテナンスや維持のため、ドキュメントオーナーを明記すると良いとされています。 そのためドキュメントの冒頭にドキュメントのオーナーを明記するようにしています。 また、オーナーが交代したり、内容が途中で変わってしまうこともあるため、変更履歴も合わせて記述するようにしています。
ドキュメントの目的
このセクションには、何を決めるためのドキュメントなのか、ということを記述します。
優れたドキュメントを作るコツは、ドキュメントにおける目的を一つに限定することです。 そのため、すべての意思決定ドキュメントは、単一の意思決定を出すための目的に限定します。 もし論点が複数存在する場合には、論点ごとにドキュメントを分割しています。
背景
このセクションには、目的に記載した、意思決定の検討事項や論点に至るまでの背景や経緯について記載します。 すでに他のドキュメントでまとめられていることも多いため、他ドキュメントのリンクを貼ることもあります。 もしくは、Notionの「Copy&Sync」機能を使って他のドキュメントの一部を切り出して添付したりして、簡潔に背景を理解できるようにしています。
あまり長く書きすぎると読み手の理解も低下するため、シンプルに記述することを心がけています。 また後述するように、ビジュアルなどを活用することも効果的に思われます。
概要
このセクションには、良い意思決定をするために必要な情報について簡潔にまとめています。 主な情報は以下の通りです。
- 現状システムの整理
- 検討した選択肢・代替案
- 意思決定の軸
- 最終的な決定事項・結論
選択肢とそれらから一つを選び出す基準作りは、意思決定の質を決める重要な要因になるため、十分に検討しきれているか注意します。 また、意思決定の軸が先に決まっていることにより、選択肢の早期な枝刈りも可能になります。
これらの情報をまとめた上で、最終的な結論も記載します。
詳細
概要に記載した項目について、実際の調査結果や緻密なシミュレーションを行い、その結果を記載します。 あらゆる情報を集めたり、厳密な意思決定を行おうとして時間をかけすぎないように注意します。
やってみないと分からないことも多く、一定のリスクを許容しないと先に進めない状況があります。 Notionの「Callout」を利用して、受け入れたリスクなどの注意事項については明示しています。
また、概要のセクションで決めた意思決定の軸に照らし合わせ、あまり重要でない項目は調査を簡略化するなどして効率化を図っています。
3ヶ月の運用の結果
私の所属するデータプロダクトチームでは、2023年12月に上記のドキュメントフォーマットを決定しました。 それ以降、全ての意思決定ドキュメントをNotionの一つのデータベースに集約しました。 また、開発における設計フェーズにおいては、このドキュメントを作成した上でチームレビューを行うプロセスを導入しました。 これにより、開発フローの中で、本ドキュメントが自然と運用できることを目指しました。
呼び方の問題
このドキュメントを決める際にはDesign Documentを参考にしていたため、当初DesignDocと読んでいました。しかし、実際の運用としては、各検討タイミングにおける意思決定を整理するドキュメントとなっていました。DesignDocのように中長期にわたってメンテナンスされるものを運用することは現実的でありませんでした。のちのち、Architectural Decision Record（ADR）について知りました。こちらの方が実態と近かったため、現在はADRと呼ぶよう変更しています。
また、DesignDocと呼んでいた時期には、実態からずれていることでメンバーが混乱してしまう、といった事象も生じました。実態に沿った形へ名称を統一するなどの取り組みは、混乱を防ぎ意図を正しく伝えることができるため、ドキュメントを浸透させるために注力すべきことだと改めて感じました。
より良い目的設定や、多くの選択肢が出てくるようになった
このドキュメントでは、目的や背景を最初にまとめていきます。その過程で、目的について立ち返るプロセスが発生します。この時、より本質的な目的や問題設定を行えることがあります。実際に、事前の検討段階で工数大と予測して省かれてしまっていた要件がありました。しかし、目的を整理し直してみると、それが営業観点で重要な要件であり、かつ実際には工数もそれほど変わらないと分かったこともありました。
また、選択肢を検討している場合にも、目的を意識しながら進めることができます。例えば、より工数を少なくするためにはどのような手段が取りうれるのだろうか、というように考えることで、新しいツールや技術の採用を検討することにもなります。また、なんとなくやらないといけないと思っていた作業が、目的に照らし合わせると不要であると気づいたこともありました。
意思決定に関する自信の醸成と型化
この3ヶ月で、チーム内で9つのドキュメントが作成され、3人がドキュメントを作成しました。 ドキュメントのレビューはチームメンバーがお互いに行いあい、曖昧な点や検討が不足している部分などについては事前にコメントし合いました。 アーキテクチャ選定に関する意思決定が透明化され、事前にトレードオフなどを認識した上で次に進むようになったため、自分たちの意思決定に自信を持てるようになったのではないかと思います。
また、ドキュメントを作成した3人のうちの1人はチームに来てくれているインターン生でした。 ドキュメントのフォーマットに従うことで、検討した選択肢などを列挙した上で、実装詳細を詰めていく、という意思決定プロセスを体験してもらうことができました。 複雑な検討が必要な開発内容だったものの、良い実装案の提案・実装を行なっていただきました。
加えて、初めてドキュメントを書く際には、書き方に戸惑うことも多いことがわかったため、今後はドキュメントの意図や書き方についてより丁寧に説明していきたいと思っています。 ちなみに、フォーマットを細かく規定することは避け、一般的な意思決定のやり方や思考の仕方について整理することで、自然と書くべき内容を決めてもらうことが出来るようになればと考えています。
ビジュアルの活用
入社以来、これまで多くのドキュメントを書いてきましたが、ひとつ課題に感じていたのが、ビジュアルが不足しがちという問題でした。アーキテクチャ図もそうですが、業務フロー・シーケンス・意思決定ツリーといった様々な情報を文章で表現してしまうことが多く、直感的に理解しにくいドキュメントを作成してしまっていました。
意思決定ドキュメントを正しく機能してチームで運用できるようにするためには、なるべくビジュアルを活用しドキュメントの理解を容易にすることが重要だと考えています。
そこで、Figjamをノバセルの全開発者分のライセンス分購入することにしました。すでに社内でFigmaが導入されていたことや、豊富な機能を持ちつつ利用料もリーズナブルだったことが決め手です。
また、Notion上のビジュアルとしてはMermaid記法を利用することもあります。 自然言語で図の内容をLLMに伝え、Mermaid記法のコードを書き起こしてもらうこともあります。
Figjamは、ドキュメンテーションの他に、以下のようなシーンでも利用されています。
- チームの振り返りでのホワイトボードとして
- ブレインストーミングの場として
- 意思決定ツリー・マッピングなど、ディスカッションの補助資料として
Figjamの導入は、ドキュメンテーションのみならず、コミュニケーションにおいても大きな助けとなるツールになりました。
まとめ
本記事では、エンジニアのためのより良い意思決定のために、ドキュメンテーションを頑張っていますという話についてご紹介しました。 State of DevOps Report 2023 でもドキュメンテーションの重要性は強調されています。 今回3ヶ月という短い期間での取り組みではありましたが、実感できる効果もあり、今後も改良を重ねつつ続けていきたいと考えています。
一方で、このようなドキュメントが、後々振り返った時のチームや個人への糾弾の材料となるのではないかと危惧したこともありました。 しかし、この3ヶ月の運用の中でその懸念は杞憂だと思うようになりました。 透明性の高いドキュメントに情報がまとめられ、チームのレビューフローにも組み込まれるようになったことで、誰かひとりの責任になることはありません。 そして、このプロセスを踏むことにより、意思決定の質を担保することが出来るようになりました。 また、必要な情報がしっかりとまとめられていることにより、振り返りの際にも建設的な議論が出来るように思います。
エンジニアリングとは問題解決の手段であり、よりシャープな問題設定・解決策を提示することも重要なスキルの一つです。ドキュメンテーションがその助けとなることを感じることが出来た3ヶ月でした。
