#note
[https://www.industrialempathy.com/posts/design-docs-at-google/](https://www.industrialempathy.com/posts/design-docs-at-google/)
see also [[Architecture Desision Record]]
> As software engineers our job is not to produce code per se, but rather solve problems.
Design Docの目的
- Early identification of design issues when making changes is still cheap.
- Achieving consensus around a design in the organization.
- Ensuring consideration of cross-cutting concerns.
- Scaling knowledge of senior engineers into the organization.
- Form the basis of an organizational memory around design decisions.
- Acts as a summary artifact in the technical portfolio of the software designer(s).
書くハードルを下げるためにもフォーマットを大事にするのではなく、合理的なフォーマットを選択する
# 書くべき内容
## Context and scope
- facts
- 背景や影響範囲などを明確にする
- 機能要求のためのドキュメントではないのでなるべく簡潔にする
## Goals and non-goals
- requirments
- 箇条書きで達成したいゴールを書く、またゴールでないものも含めるのを忘れないようにする
## The actual design
> The design doc is the place to write down the trade-offs you made in designing your software
- 具体的な手段や他の選択肢と比較してこれがベストな選択肢であることを書く
- 定まったフォーマットはないが、いくつかうまくいっているパターンがある
### System-context-diagram
### APIs
- 具体的なインターフェースのコピペではなく、トレードオフに焦点をあてるのが重要
### Code and pseudo-code
- 実際のコードや疑似コードはなるべく書くべきではない
- 抽象的なアルゴリズムなどを説明するべき
- 必要に応じてプロトタイプへのリンクする
### Degree of constraint
- 解決手法の取り得る制約の度合いも大きな要因の1つになる
- 例えば、全くの新規プロジェクトで好き勝手に実装を行っていい場合 ( [[Greenfield Software Project]] ) もあれば、レガシーシステムでそもそも組み込むための制約が大きい場合などプロジェクトによって様々である
## Alternatives considered
- 他の取りうる代替案を列挙する
- ここでも主にトレードオフに注意する
- このセクションが「選択された解決法が最も良い選択肢である」ことを述べる上で最も大事な章になる
## Cross-cutting concerns
- プライバシーやセキュリティーなどは常にどの Design Doc でも扱うべき
- これらを専門的に扱うチームにレビューを依頼するのは重要で Google ではプライバシーのための Design Doc を作るルールになっている。
- これらはプロジェクトが実際に開発に入る前までにレビューをもらっておけばいいものである
- 最初からこれらの非機能要件を考えることが重要
## The length of a design doc
- 忙しい人たちにも読んでもらえるようある程度小さくなくてはいけない
- Googleでは、大きめなプロジェクトの場合には10-20ページがちょうどいいらしい
- 1-3ページの "mini Design Doc" も有用で特にアジャイルプロジェクトではこれらを活用していくのがいい
- ただしやり方や項目は省略することなく行うことが望ましい
# Design Docはいつ書かかないべきか
# Design Docのライフサイクル
## Creation and rapid iteration
## Review
## Implementation and iteration
## Maintenance and learning
## Template
EN
text
```
# Context and scope
# Goals and non-goals
# The actual design
# Alternatives considered
```
JP
text
```
# 課題感
# 達成したいこと・スコープ外のこと
# 解決方法
# 代替案の検討と比較
```