初めまして！データウェアハウス開発部 保険者基盤Gの石井です。 今年、JMDCではアドベントカレンダーに参加しています。 qiita.com 本記事は、JMDC Advent Calendar 2024 21日目の記事です。
はじめに
保険者基盤Gでは健康保険組合から受領したレセプトや健診、適用台帳データを取り扱っています。
私が担当する適用台帳データは保険組合で管理する被保険者証記号・番号に紐づく個人情報のデータであり、レセプトや健診データと紐づけることで各個人が「どんな治療を受けて、どんな薬を処方されたのか」を追跡することが可能となります。
さて、私がこの会社に入社して早1年が経過しました。台帳チームはここ数年で人員の入れ替わりが多くあったため、現在はチームメンバー全員が比較的社歴の浅いメンバー構成となっています。そのため、自分たちが取り扱うシステムについて仕様の背景に不明点が生じた際、それが文書化されていない限り情報を見つけ出すことが非常に困難であることがチームの課題となっています。
現在台帳システムはAWSへの移行プロジェクトの最中であり、日々様々な意思決定がされています。それらの決定事項は背景とともに文書として残しておかなければ、またいずれ同じことが繰り返されることでしょう。。。
そこで設計背景を残すためのフレームワークとしてDesign Docについて調査をしたのでまとめます。
Design Docとは？
Design Docはソフトウェア開発における設計プロセスについてWhat・Why・Howに焦点をあてて記録する設計ドキュメントです。
ドキュメントを書くのは実装担当者で、実装を始める前にプロジェクトの背景や目的、実装戦略、検討した代案などを書き出します。
そしてそれをもって関係者との共有、議論を行うことによってプロジェクトの方向性が明確になりチーム全体の意識が統一されます。この「共有」がDesign Docの運用においては非常に重要と言えます。Design Docは単なる設計ドキュメントではなくプロジェクトの仕様決定や技術的な選択肢についての議論を促進し、開発チームが的確な決定を行うためのコミュニケーションツールでもあるのです。
またDesign Docは常時更新される動的なドキュメントであることも特徴的です。実装を進める中では技術的な再検討が必要になることがあります。その際の議論の内容、問題解決の過程をDesign Docに記録します。これにより技術的選択の背景や理由をチームメンバーが理解できるようになります。またその際はDesign Docを通じて元の設計意図を確認しながら議論を行うことで最終的な成果物が期待通りのものになる確率が高まります。
導入により期待される効果
- プロジェクトの理解の浸透
- 体系化されたドキュメントをもってチームにプロジェクトの背景や目的を共有することでメンバー間での方向性の相違を防ぎます。
- 事前に目的や実装方法が共有されることでプルリクのレビューもスムーズに！
- 情報の拡散防止
- 実装方針などについてはMTGやチャットツール、タスク管理ツール、プルリク上など様々な場所で議論が行われることで情報が拡散しがちです。それらを一元的に記録しておくことで後々情報を探しやすくなります。
- 大きな手戻りのリスク軽減
- プルリクの段階まできて「ここの考慮してる？」などの指摘により設計からやり直し、、なんてことも実装前のレビューで気付けるチャンスが得られます。
- チーム間の衝突の防止
- 大規模なプロジェクトで複数のチームが同時に作業をする場合に、Design Docを通じてそれぞれの作業範囲や技術的な決定事項を明確にすることでチーム間の無駄な衝突を防ぐことができます。
テンプレート
Design Docは仕様書や設計書のような厳格なフォーマットは存在しません。チームによって、プロジェクトによって必要な項目を選びとって作成します。よってここではどのようなケースにおいても記載することが望ましい項目を挙げます。
◎ 目的と背景
このプロジェクトが始まった理由や、解決すべき具体的な課題を詳細に記述します。
この部分がしっかりと書かれていることで、関係者全員が同じ理解を持って作業に取り組むことができ、無駄な作業や誤解を防ぐことができます。
◎ スコープ（ゴールと非ゴール）
具体的に何を実現するのかを定義します。具体的な目標を設定することで、プロジェクトの方向性がぶれずに進行し、最終的な成果物が期待通りのものになるサポートをします。
またスコープに含まないと決めた事項を明記することで、考慮したけれどあえてスコープから外してるのか、単に考慮漏れなのかが伝わりやすくなります。
◎ 想定リスク
技術的な制約やリソースの制限、スケジュールの厳しさなど、プロジェクトを推進する上でのリスクを明確にします。これによりリスクに対する適切な対応をあらかじめ想定することができ、問題に対して柔軟に対応するサポートになります。
◎ 技術的選択肢とトレードオフ
設計を進めるにあたって考慮した技術的な選択肢や、それらの選択肢間のトレードオフを記載します。代替案やそれぞれのメリット・デメリット、選択した理由も明記します。これにより、将来的に設計の妥当性を確認しやすくなります。
おわりに
Design Docの運用について調べていると、様々な記事、ブログでそれぞれ違った運用が紹介されており混乱します。ただそのどれもに共通していた内容が2つありました。
- Design Docは意思決定の背景・意図を記録するための文書である。
- Design Docはチームのコミュニケーションを活発にするためのツールである。
Design Docはその自由度の高さから導入がしやすいと同時に、ルールを確立していかないと形骸化しやすいリスクもあるように感じます。設計の記載の粒度や更新のタイミング・頻度などはチームによってルールに大きな違いがでる部分だと思いますが、このドキュメントを記載、更新することが大きな負担になり最終成果物の品質の低下に繋がっては元も子もありません。まずは最低限、「背景を残すための議事録」のようにざっくりと運用をはじめてみるところから試してみるのがよいかと思いました。
「この辺のことはあの人に聞けばわかるから」
これに聞き覚えがあればぜひ導入を検討してみましょう。
最後までお読みいただきありがとうございました！
明日22日目は、野田さんによる「Kaigi on Rails 2024 に参加しました」です。お楽しみに！
JMDCでは、ヘルスケア領域の課題解決に一緒に取り組んでいただける方を積極採用中です！フロントエンド /バックエンド/ データベースエンジニア等、様々なポジションで募集をしています。詳細は下記の募集一覧からご確認ください。
hrmos.co
まずはカジュアルにJMDCメンバーと話してみたい／経験が活かせそうなポジションの話を聞いてみたい等ございましたら、下記よりエントリーいただけますと幸いです。
hrmos.co
★最新記事のお知らせはぜひ X（Twitter）、またはBlueskyをご覧ください！
Tweets by jmdc_tech twitter.com
bsky.app
