Design Doc
実装前に書くべきデザインドキュメント（設計資料）について。
2 minute read
目的とメリット
- 実装前に書き出すことで思考を整理できる
- 思考を整理した結果がドキュメントとなり、他の人にも共有できる
- 実装後にドキュメントを書くよりも退屈しない
- 考えながら実装した場合よりも、作業の手戻りが少なくなる
デザインドキュメントはGitHub Issueで書く
Design DocはGitHub Issueにマークダウンを使用して書きましょう。 メリットとしては以下の通りです。
- 実装に近い箇所で書いて残すことができる
- ドキュメントをそのままIssueとして使える
- 機能追加として起票されたIssueに追記できる
Notionと比較した結果、現時点ではGitHub Issueが最適だと判断されました。
デザインドキュメントが必要か不要かの判断基準
- いくつかのIssueに分割が必要な大きいIssue（Epic）であること
- Story Pointsが5以上であること
design docラベルがついていること
Note
design doc ラベルは誰でも付けられます。
自分が担当ではなくても、このタスクにはデザインドキュメントが必要だと思ったら、ぜひ付けてください。デザインドキュメントを書く人
- Issue起票者：書けるところだけ書けば良い
- 担当者（Assignee）：実装着手前に書くこと
デザインドキュメントに必要な内容
Purpose（目的）
達成したい目的や、解決したい課題を書きます。
Background（背景）
前提になる知識や参考になる情報やリンクを書きます。
Proposed Solution（提案する解決策）
目的を達成するために考案した解決策を書きます。
Considered Alternatives（検討した代替案）
検討したが採用しなかった代替案があれば書いておきましょう。
Implementation Design（実装設計）
詳細すぎない範囲で、実装の設計を書きます。
書き方の注意点
- 要点を自然言語で書き、詳細は書きすぎないようにしましょう
- GitHub Issue Templateを使うと、必要な見出しをIssueに挿入できます
- Issue TemplateやLabelがない場合は作成しましょう