デザインドキュメントを知るための参考リンク集

自分もデザインドキュメントを始めようと思ったので、デザインドキュメントとは何かを知るために情報収集した結果と簡単な自分の考えのまとめ。

デザインドキュメント概要

• [2007-06-01] Software Engineer in Google - Google Developer Day Tokyo 2007
  • Googleのソフトウェアエンジニアがどのように開発しているのかという発表で、プロダクト開発の流れの中でデザインドキュメントを利用していることが説明されている
  • Why(背景や目的)、How(おおまかな設計、コードを見てわかることは書かない)、Who(メンバ、誰にコンタクトすればそのプロダクトについて知れるか)、セキュリティやプライバシーに関する考慮、テストやモニタリングをコーディング前に記述する。開発を進める中でできるだけ乖離しないように修正する。
  • この発表内容に関する聴講者のメモ: Google のソフトウェア・エンジニアリング
• [2009-11-17] Google の Design Doc について
  • Software Engineer in Googleの発表や複数のOSSにおけるデザインドキュメントを引用した上で、自分1人で開発するプロジェクトにおけるデザインドキュメントに書くべき内容のまとめ
  • コードを書く前に文章化することで問題を整理して目標を明確化する。また、ソフトウェアのメンテナンス性・再利用性向上に役立てる。
  • 依存ライブラリやバージョンを書くべきかは疑問だが、todoのように今はやらないことを整理しておくのはよさそう。
• [2016-06-21] 残業も減らせる!? 上級エンジニアになるためのDesign Doc超入門
  • ソフトウェア開発におけるコミュニケーション手段の1つとして、利用ユーザ向けではなくその開発者・技術視点としてのドキュメントとしてのデザインドキュメントの紹介
  • 少し古い記事だからかもしれないがあまり納得できない。思考の整理という意味ではデザインドキュメントである必要はないし、作業時間を短縮する説明にもなっていない。
• [2018-12-16] #1: デザインドキュメントを書こう
  • マイクロサービスでは複数のサービスと連携するため、サービスの分割や全体設計が重要であり、これを十分に議論するためにデザインドキュメントを作成するという考え
  • 確かに、マイクロサービスのように変更が他のチームなどに影響する場合は変更の必要性も認識される必要があり、デザインドキュメントが有効に機能しそう
• [2020-07-06] Design Docs at Google
  • GoogleエンジニアによるGoogleのデザインドキュメント詳細
  • デザインドキュメントを書くことによるメリットや何を書くか、どのくらい書くか、何を書かないかがまとまっており非常に参考になる
  • その日本語訳: [2020-08-03] 【翻訳】Googleのエンジニアがソフトウェア開発する時に必ず書くドキュメント「Design Docs at Google」
• [2021-03-04] Design Docs のいけすかなさ
  • 他の参考資料とは異なりデザインドキュメントの欠点や課題について議論している。
  • デザインドキュメントが上手くいかない点や過度に期待されている点、点などが指摘されている。
• [2021-06-30] 緩やかに死んでいくシステム
  • Cloud Native Lounge #2における発表(発表スライド および 発表録画)
  • ソフトウェアを継続的に開発するために必要なものはいくつもあるが、そのうちのドキュメントに焦点を当て、AWSにおけるデザインドキュメントを用いたメリットの紹介
  • 継続的な改善のためにはなぜ現在の設計になっているかが重要で、これをドキュメントとして残すという考えがわかりやすい

デザインドキュメントが何なのかについては Design Docs at Google が詳しいが、なぜデザインドキュメントが必要なのかについては 緩やかに死んでいくシステム が納得感が高かった。
開発する機能について、なぜその開発が必要なのかを納得してもらうために、また何を検討して何を検討しなかったのかを残すためにデザインドキュメントを作成する。開発するモチベーションを伝える部分は開発着手前に記載して共有し、それが伝わったらPoCをしながら検討結果を残してなぜ最終的な設計になったのかを残す。プルリクレビュー時にデザインドキュメントがあればなぜこの実装なのかわるのでレビューしやすいし、後日機能改修時にデザインドキュメントがあれば同じ検討をしなくて済むし、対象機能のコンテキストが理解しやすくなる。
逆に開発するモチベーションや実装方法、その他トレードオフが明確な場合はデザインドキュメントを作成する必要がない。コミュニケーションや合意形成が容易な場合はわざわざデザインドキュメントを作成する必要はない。とはいえ、どういった場合にデザインドキュメントが不要かは単にデザインドキュメントを作成する以上に難しそう。

その他のドキュメント

ADR

• Architectural Decision Records, 日本語訳は定まったものはないが、アーキテクチャに関する
• Lightweight ADR, Markdown ADR(MADR)などいくつかバリエーションはあるがどれも明確な違いはなさそう。MADRがMarkdownを想定することくらい
• 目的はデザインドキュメントとほぼ同じで、なぜそのような判断を行ったか(Why)を残すため
  • ADRとデザインドキュメントの違いを明確に延べている資料は見付けられなかった
  • ADRは1つの判断につき1つのファイルを書くことを推奨している例や推奨記述項目が少ない例が多く、より書きやすく(読みやすく)することを重視している。デザインドキュメントは複数の選択肢(判断)を踏まえた最終的な判断を記載することを推奨している例やアーキテクチャに加えてセキュリティやテスト、運用など複数の内容を記載することを推奨している。
• 参考
  • Homepage of the ADR GitHub organization
  • 導入した記録ではなく導入“しなかった”記録を残す LADRによるアーキテクチャ意思決定記録のすすめ
    • インタビュー形式なのでLADRに対する期待などがわかりやすい。これだけ読むとデザインドキュメントとの違いがわからなくなる。
  • Architectural Decision Records（ADR） 実践備忘録
• 事例

  • Ubie事例: [2021-06-16]ユビーが長期に渡ってソフトウェアを進化させ続けるためのドキュメンテーションプラクティス

  • スタディサプリ事例: [2021-04-05]〜その意思決定を刻め〜「アーキテクチャ・デシジョン・レコード(ADR)」を利用した設計の記録

  • elastic事例: Elastic Cloud on Kubernetes (ECK)

デザインドキュメントと同じくWhyを残すためのドキュメントであるが、1つのファイル・意思決定が小さくなることを想定している。これは、デザインドキュメントは対象システムがなぜそのような設計になっているか、ADRは開発者がなぜそのような判断を下したか、に焦点を当てておりドキュメントを残す目的が多少異なる？例えば、利害関係者が多くて判断を下すことが難しい場合にADRがより有効になる？

PRD

• プロダクト要求仕様書(Product Requirements Document)。
• デザインドキュメントやADRと合わせて作成するドキュメント例として挙げられていたが、こちらは技術的な内容ではなく主にPdMが中心となって作成し、何(What)を作るのかに焦点を当てたドキュメント。
• 参考
  • [2019-11-11]はじめてのPRD
    • プロダクトの軸を定めるために必要なドキュメントとして紹介。リーンキャンバスやインセプションデッキとの比較によりイメージがついた

PRDは作成する目的も内容もデザインドキュメントと明確に異なる。

仕様書

いわゆる仕様書。略。

デザインドキュメントの具体例

• [2009-09-02] WebKit WebScoket design doc
  • WebKitにおけるWebSocketの実装に関するデザインドキュメント。
  • かなり細かく、具体的なコードまで記載されているのでこれだけ読むと関数コメントからdoxygen等でドキュメント生成でよいのではと思ってしまう。10年以上前の事例なので今と状況が違うから、と判断してよいのだろうか？
• Chromium Design Documents
  • Chromiumにおけるデザインドキュメント一覧。かなり大量にあるので参考になる？
• [2019-12] Prometheus Exemplars
  • Prometheusのプルリクに関するデザインドキュメント。 e34.fmで紹介されていた。
  • 最近のOSSでのデザインドキュメント事例という意味で参考になる。他のプルリクでもデザインドキュメントが記載されているものもあるが、かなりフォーマットや記載内容にばらつきがある。OSSだから？