デザインドキュメントについて
こんにちは、 @kz_morita です。
先日行われた勉強会 でデザインドキュメントというソフトウェア開発時に各ドキュメントについて聞いて,興味が湧いたのでしらべてみました.
デザインドキュメントとは デザインドキュメントは Google などの企業でソフトウェア開発を行う際に一緒に書かれるドキュメントのことです.
ソフトウェアがどのような問題をどのように解決するのかを,ソフトウェアよりより高いレベルで伝えるための手段としてもちいられます.
何を書くべきか このドキュメントには,実装のアプローチや,主要な設計上の決定事項,考慮されたトレードオフなどが書かれます.
何を書くべきかという明確なルールはないためそれぞれのプロジェクトに合った形で改造していくのが良さそうです.
以下に自分が参考にした一例を載せます.
- プロダクト開発・機能開発・改善の背景 - 課題は何か=何を解決するのか - システムの技術的概要, アーキテクチャー図 - スコープ - プロジェクトの参加者 - 用語集 - 選定した解決手段について - 選定の根拠、トレードオフ - 詳細なアーキテクチャー図など - PoCの内容と結果 - 選定しなかった解決手段について - 手段の概要と、不採用の根拠 - 外部依存の概要 - 機能そのもの、解決手段についてセキュリティ観点からの考察 - 現時点で考えられるリスク - リスクの概要 - 考えられるリスクへの対応策 - 現時点で対応策を取らない理由 - テスト観点からの考察 - 運用観点からの考察 - 運用時の考慮事項 - 障害の発見と復旧手法 - References - etc...etc.. 特に重要なのは,考慮したけど採用しなかったものや,技術選定の際の選定基準やトレードオフ,またその技術を使うことで起こりうるリスクなどになるかなと思います.
デザインドキュメントの価値 メリット ドキュメント化することにより,早い段階で設計のレビューを行ったり問題点を話し合うことで手戻りがすくなるほか,組織内での合意形成などにも役に立ちます.
そして何より,考古学をしなくてよくなるということが最大のメリットに感じました.
ここで考古学といったのは,例えば古いシステムの古い仕様について聞きたいときに,プロジェクトに当時在籍していた人がすでに退職してわからなかったりする場合には,コードやコミットログ,チャットのログなどから状況を推測する必要がある事象のことです.