😸
データ基盤を支えるdesign doc
この記事はdatatech-jp Advent Calendar 2022の12月11日の記事です！
概要
自チームでデータ基盤を作っていく際に使っているdesign docの紹介と、導入背景をここに記します
感じていた課題感
- レビュアーにアサインされてプルリクを見るときに「このプルリクはどういう背景があって、どういうコードを書いたのか、どういうテストをしたから大丈夫なのか」を汲み取るのに時間がかかるなって思っていた
- 備忘録的にissueにたてる、とりかかるときにタイトルだけ埋めたissueを立てて走り出す、ということが多く感じて、事前に整理しておくともっと効率が上がるのではと思った
- データ基盤を作っていく際に、ログやテーブルの値の意味などをエンジニアにヒアリングすることがあるが、それをちゃんと蓄積したいと思った
- これに関しては、別途Notionで蓄積してるものがあるのですがGithubにまとまっていた方が見やすい、issueとして立てていく方が運用に乗りやすいなと思いました
採用しているdesign docテンプレ
# Goals (この取組のゴール)
# Non-goals (あえて含めないと決めたこと)
# Background (背景)
# Solution / Technical Architecture
## Data source
## Model / Materialization / Partition and cluster
## snapshot
### stg層 (view)
### mart層
# Testing (どんなテストをしてデータの正しさを担保するか)
Goals (この取組のゴール)
- 何を達成したいのかを書く場所です
Non-goals (あえて含めないと決めたこと)
- レビューしてるときに「あれは考慮に入れるんだっけ？このプルリクのスコープなんだっけ？」ということが出てくるのはよくあるかなと思っています
- 考慮したけどあえてスコープから外してるのか、単に考慮漏れなのかが伝わりやすくなるために設けています
- 気に入っている項目です
Background (背景)
- 一番重要視している項目です
- 後々どういう背景でこのような実装がされているか振り返るときに役に立つと信じています
- ここは必ず埋めてもらうようにしています
Solution / Technical Architecture
- どう実装していくかの詳細です
- 以下の項目はdbtを用いたデータ基盤を想定しています
Data source
- どのData Lakeを参照するつもりなのかを書く場所です
Model / Materialization / Partition and cluster
- さらに詳細なモデリングを記述する場所です
Testing (どんなテストをしてデータの正しさを担保するか)
- generic testを書くのか、singular testを書くのか、それともテスト用のアドホックなクエリで確認するつもりなのかなど、どんなテストをしてデータの正しさを担保するかを明記する場所です
design docを運用していくのに心がけてること
-
テンプレで大切にしたいこと
- 簡単に書ける(書くことに対する心理的ハードルが低い)
- 全部埋めなくても良い
- 目的と背景は必ず埋めること
- テンプレ自体はGithubのisue templateとしておき、書き始めやすくする
-
いつdesign docを書くか
- issueを起票するとき
- タイトルだけじゃなくて目的や背景だけでもセットで書いておくと後々手を出しやすい
- 実装前に相談したいとき
- 相談のアジェンダとしても使える
- 実装が複雑そうで頭の整理をしたいとき
- 実装においてどこが難しくなりそうなのか、自分で整理するときのために
- issueを起票するとき
-
2・5・8意識
- design docの運用というよりチームで心がけてることです
- 2割、５割、8割の完成度で共有するの意味です
- 「2割ですが方向性だけ見てほしいです」「5割までブラッシュアップしたので詳細部分も相談したいです」「8割まで仕上げたのでこれで実装していくつもりです」みたいにしてフィードバックをもらう部分の期待値調整をします
- 「design doc2割のたたき作ったので方向性の齟齬ないか確認お願いします」のようにdesign docをサラッと作ってサラッとフィードバックを求めるときに使えます
- フィードバックを求められた側も「これは2割だから大枠の方向性だけサラッと見よう」というふうに期待値に応じたレビューができます
3ヶ月ほど使ってみて
- プルリクをレビューする際に前提情報がしっかりある状態になったのでレビューしやすくなったなと感じます
- issueに
design docというlabelがついたものが蓄積されていってる感覚と、議論の内容が残ってるなという感じはあります- これに救われたーということはまだありません
- 実装する前にdesign docを予めレビュアーと共有することで大きな手戻りがなくなってきたなと感じます
- 実装前、実装時、レビュー依頼時のコミュニケーションのインターフェイスができたのは話しやすく感じています
- 今後もこの取り組みに関してアップデートがあれば反映していこうと思います
以上！
design docを考える際に参考にさせてもらってた記事
Discussion