はじめに
皆さんこんにちは。株式会社サイカでソフトウェアエンジニアをやっている鹿島(kashitaka)です。
皆さんの開発組織では設計書（Design Doc）をどのように運用していますか？ Design Docをめぐる運用は開発組織全体の広い取り組みとしてプロセスに落とすことが難しく、チームごとに独自で運用しているなど取り組みが限定的だったりします。（社内の別チームは開発ドキュメントなどないチームもあったり）
サイカでは Design Doc を開発組織全体として設計し運用しています。このDesign Docの運用体系は2021年ごろに定義し、 約2年運用して組織的に定着しています。 今回の記事ではサイカがどのように Design Doc を管理・運用しているのかをご紹介します。
この記事がチームや組織のDesign Docの運用に悩んでいる方、これから Design Doc の運用を始めてみたい方の助けになれば幸いです。
XEPとArchitecure Guide
サイカでは Design Doc を次の2種類に分けて運用しています。
- Xica Enhancement Propasal (XEP)
- Architecure Guide
Xica Enhancement Propasal (XEP) は、開発プロジェクトにおける認識合わせと、後世に記録を残すことを目的にしたドキュメントです。 開発スコープの変更点を記載し、アーキテクチャの選択肢やトレードオフ、API設計、ER図などを記載します。 こうすることで、開発プロジェクトにおける変更点の議論の材料となったり、スケジュール見積りの材料になったりします。 また、開発当時の意思決定の記録を残すための設計書として運用していて、 新たにプロジェクトに加入したメンバーが XEP を読むことで当初の設計、その変遷記録、意思決定の過程を即座に学習することができるメリットを持っています。
一方で、Architecure Guide はシステムの現状の作りが知れるものであることを目的として、現行のアーキテクチャを反映しています。これにより、現在のシステムの状況を即座に把握することができるメリットを持っています。例えば、システム構成の概略図や、サービスの役割、複雑なトランザクションのシーケンス図など、そのシステムの開発に関わる上で、最初に知っておくとキャッチアップが楽になることを記載していきます。
ここからさらに、XEP と Architecture Guide がそれぞれ生まれた経緯や、管理方法など詳細をご紹介します。
そもそもなぜ２種類あるのか
サイカでも Design Doc に関する課題があり、たびたび議論のテーマとなりました。
- 開発プロジェクトのときに毎度Design Docを起こしているが情報が古くなっているものがある
- 読み手はそれが今のシステムの作りと一致しているかわからない
- 過去のDesign Docをメンテし最新化するコストや、その確保の方法
などの問題を抱えていました。そもそもDesign Docは継続的にメンテしていくものなのか？開発プロジェクトで書き起こして終わりでいいのか？
いくつか議論を重ねていくうちに、Design Docに求められる要素が整理されていき、下記のユースケースが挙げられました。
- 開発プロジェクトで実装する前に何を作るかを明らかにしていきたい
- 後世に開発当時の意思決定の記録を残していきたい
- 開発に関わっていないエンジニアでもDesign Docを読めばすぐにキャッチアップできるようにしたい
- 組織が拡大しても続けられるシンプルでメンテが負荷にならないDesign Doc運用をしたい
これらのユースケースをうまく運用に落とすべく、いくつかOSSプロジェクトなどのDesign Docの運用方法を調べたところ、以下のような形でメンテしているプロジェクトを見つけました。
- Issueの解決方法と変更点はProposalを作って議論・記録
- 開発に関わりたい人向けにはContribution Guideのようなものを用意
サイカでもこの “Proposal” と “Guide” の方式を取り入れました。 特にProposalはKubernetesではKEP、PythonはPEPということで、XicaではXEP（ゼップ）と名付けました。ゼップの語感が呼びやすく、組織内でものすごく定着しています✌️
2つのドキュメントが果たす機能
このようにそれぞれの要件と経緯から誕生した XEP と Architecture Guide ですが、具体的にどのように作成し、実際のプロジェクトの中で機能しているのかをご紹介します。
XEPは開発プロジェクトの設計段階で執筆し、設計レビューやスケジュールの見積でも加筆します。またプロジェクト中に変更があった場合なども加筆し、チーム内で常に参照されます。 ただ、バグ修正など含めて全ての変更でXEPを書くわけではありません。 あくまで設計に論点がある変更や、複数名のエンジニアが関わって同時に開発する規模のプロジェクトで執筆します。
Architecture Guide は開発プロジェクトが終了し、何か特筆すべきことがあれば記載します。プロジェクト以外でも基本誰でもコミットできるので、「ここわかりにくい」というところがあればいつでもPRを送れるようになっています。
管理方法
これらのDocumentはGithubで Design Docレポジトリを作って管理しています。 以前はXEPはコンフルで管理していましたが、レビューしやすいようにGithubに集約しています。
Desing Docレポジトリのディレクトリ構造
- XEP
- サブシステム名
- 開発プロジェクトごとにフォルダを切って作成。（yyyyMMddをフォルダのプレフィックスにすると時系列を追いやすい）
- サブシステム名
- Architecture Guide
XEPはテンプレを用意
新しいXEPを作るときは下記のテンプレをコピーします。
開発プロセスへの組み込み
プロセスを標準化する中で、次のようにXEPとアーキテクチャガイドを編集するようにしています。
- 🚩 プロジェクトスタート
- 設計 : ここで新しいXEPを起こす
- 設計レビュー : XEPはチーム内でレビュー、チーム外のTech Leadからもレビュー
- 実装・テスト
- リリース
- 必要に応じてArchitecture Guideの更新
- 🎉プロジェクト終了
これらの運用により、プロジェクト当時の変更を詳細に記録し、メンテ工数をそれほどかけずに、Architecture Guideも最新化するフローを実現できます。
ユースケースで分ける Design Doc のススメ
ということで、今回はサイカのDesign Doc運用のお話でした。
Design Docは読み手の期待値やユースケースの幅広さを考えると、ドキュメントそのものが巨大化してしまい、読み手の理解度にばらつきが生じたり、記述・更新するコストが膨大になってしまうデメリットがあると思います。このデメリットが保守性を下げてしまい Design Doc をはじめとするドキュメントの最新性を保持することが困難になっている状況が生まれるのではないでしょうか。
Design Docという一つの概念を読み手やユースケースを調査して分解することで、有用かつ組織的に定着するDesign Docの運用を実現できるかもしれません。皆さんの開発組織でも参考になれば幸いです🙏
ついでに宣伝：過去記事ではサイカでのマイクロサービス化の取り組みなどを紹介していますので、気になる方はチェックしてみてください。
