概要
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上でリポジトリ管理する形もありかも
参考