Design Docとは

Design DocはGoogleに代表される最先端の技術企業で取り入れられている設計ドキュメント。

単にドキュメントの書式だけを指すのではなく、書いた後の使い方までを含めた「開発のやり方」に繋がっているドキュメント方式であり、エンジニアがこれから開発しようとするソフトウェア設計の基本的な要点

何を(What)・何のために(Why)・どのように(How)作るのか。を説明するために書くもの
要点だけを書き、それ以上詳細なことは「書きすぎない」ことが重要

• 開発者がコーディングに着手する前にソフトウェアシステムまたはアプリケーションの開発する人が作るドキュメント
  • ソフトウェア設計における仕様書や設計書とは別物と捉えた方が良い
  • 仕様書、設計書は作成した上でのDesign Docの作成となる
• 高レベルの実装戦略と主な設計の決定事項がまとめられており、設計において考慮されトレードオフに重点を置いて文書化されている

ソフトウェアの重要なポイント

• ソフトウェアを開発するエンジニアにとって重要なことは、コードを書くことではなくソフトウェアによってある問題が解決すること
• 設計書のようなテキストを使用するということは、プロジェクトを進める中での初期段階で問題を解決することができるツールになるのではないかと言っている
• なぜなら、実際のコードよりも簡潔で理解しやすく、当事者にとってある問題とその解決策を高いレベルで伝えることでできる

Design Docを使うことでのメリット

• 変更を加える際に設計上の問題を早期に特定することで、手戻りが少なくなる
• 組織内の設計に関する合意形成を達成することができる
• 懸念事項を確実に考慮できる
• ハイレベルなエンジニア(リードエンジニアなど)の知識を組織に浸透させることもできる
• 設計上の決定に関する組織の基礎を整形することができる
• ソフトウェア設計者の技術知見の中で確約された成果物となる

Design Doc: Software Design Document

先に述べたようにソフトウェア設計における使用者や設計書とは別物であるため、ガチガチな形式はないが、ただ、ルールが1つだけ存在する。

それは、Design Docを作成するプロジェクトにとって最も意味のある形で書くこと。

これだけでは困ってしまうため、ある程度有用なものとして

• コンテキストとスコープ
  • 新しいシステムはなぜ構築するのか
    • 実際に何が構築されようとしているのかをざっくりまとめる
  • 要件書ではないため、簡潔にするのがポイント
  • 客観的な背景と事実に焦点を当てる必要がある
• 目標と目標としないこと
  • システムの目標が何で、何が目標ではないのか
    • 箇条書きで表す
  • 目標でないことというのは「システムがクラッシュしてはならない」などの否定されたものではなく、目標である可能性があるものの、明示的に目標ではないことが選択されていることとする

Design Docにおけるデザインの本体

---

概要

• Design Docはソフトウェアの設計の中で決めたトレードオフを書いていくためのもの
  • 長期的に価値のあるドキュメントとなるよう作成

コンテキストで事実が述べられ、目標と目標としないことに要件があり、それをもとに具体的なソリューションを提案
なぜそのソリューションがある問題を解決できるのかという理由を記述する。
ただ、Design Docはざっくりとしたドキュメントとなるため、問題の解決策も踏まえ柔軟性を含めながら書いていくことがポイントとなる

システムコンテキスト図

多くのドキュメントでは下記のような図を使用することで、システムを拡張する際に分かりやすく、読みすくなるため、コンテキスト図が役立つ。

API

設計中のシステムが既にAPIを公開している場合は、そのAPIを記載することを推奨されている
冗長なドキュメントを増やさないためにも、面倒でもしっかり記載することが重要となる

では、何を記すのか
⇒ 設計とのトレードオフに関連する部分に焦点を当てた内容を記載すること

データストレージ

データを保存するシステムでは、保存がいつ、どのような形で発生するのかを議論する必要がある
ここでも完全なスキーマ定義をコピペするのではなく、設計とのトレードオフに関連する部分に焦点を当てた内容を記載すること

コードと議事コード

新しいアルゴリズムが記述されている以外は、コードや議事コードを含めない
設計の実現可能性を示す必要があればプロトタイプのリンクを記載する

解決策における制約の度合い

ソフトウェアへの設計へ影響を与える主な要員の1つは、設計するソリューションの制約の度合いとなる
解決策が明確に定義されているが、目標を達成するためにその解決策をどのように組み合わせればよいのかわからない場合があったとすると、変更するのが難しく、既存システムへの拡張をするとなった場合、既存のシステムがレガシーにより特定の制約がかかってしまうということを指す
この場合おいても、複数の解決策を列挙していき、想定され得るすべてのトレードオフを考慮して最善の方法を選択することに焦点を当てる必要がある

検討した代替案

検討した結果、推しの設計と同様の結果を達成できる代替の設計を列挙していく
それぞれの設計においてのトレードオフとそのトレードオフの結果から推したい設計を選択する際の最終的な決定に繋がったのかに焦点を当て記載する

選択されなかったソリューションについては簡潔に述べて良く、選択されたソリューションがプロジェクトの目標と代替のソリューションを考慮して最適である理由を明確に示す必要があることだけが重要となる

懸念事項

セキュリティーやプライバシーなどの懸念事項が考慮されているのかを示す
懸念事項が設計にどう影響を与え、どのように対処するのかを説明する
そのため、チームはこれらの懸念事項を標準化する必要がある