概要

Design Docsについて調べてみた。

Design Docsとは

Design Docsはソフトウェア設計のためのドキュメント。

決まった形式を持たず、プロジェクトにとって意味ある形で書くことをルールとしている

Design Docsは開発プロセスにおいて、以下のようないくつかのメリットを持つ。

特定の形式は持たないが、設計のコンテキストやスコープ、目標や非目標を明確にすることが推奨される。

ドキュメントの長さについては、忙しい人でも手短に読める程度の長さが推奨される。

Design Docsを書くべきかどうかは、Design Docsを書くメリットがDesign Docsを運用するコストよりも上回るかどうかが基準となる。

Design Docsは次のようなライフサイクルを持っている。

Design Docsの例には例えば次のようなものがある。

チームやプロジェクトにとって価値あるドキュメントの形を定義、理解し合う必要がありそう
- なぜ書くか（Why）、誰が読むか（Who）、どのように書くか（How）
- 特に設計書なのか、議事録なのか、人によって見え方が違うドキュメントになるとと書き手にとっても読み手にとっても辛い
ドキュメントの型を決めてしまうとその型を意識して型にはめ込んだ考え方をしてしまったり、型を出た考え方がしづらくなってしまうというリスクもありそう
- 型よりも目的の意識、理解を重要だと感じる
ドキュメントの運用コスト（レビュー・更新などのメンテナンス）がどれくらいか。そのコストを払う価値があるかよく検討する必要がある
- メルカリshopみたいに更新しないというのありかも。あるいは気づいたときは更新するかくらいの感じでも
- システムと同じく運用面をどうするかもちゃんと検討する必要がある
Design Docsが持つライフサイクルはアジャイルな開発プロセスの中に上手く組み込むことできるはず
外部公開（APIドキュメントなど）、内部公開など閲覧範囲によっても運用の形が変わりそう
レビュープロセスを手厚く行いたいのであればgithub上でリポジトリ管理する形もありかも