Design Doc
これを書くほうがいいという情報を聞いて、どうゆうものかを調べてみた。 多くは、下記の項目を含むみたい。
- タイトル このソフトウェアの名称
- 著者名 このDocを書いた人
- プロジェクトメンバー 開発に参加するメンバー
- 目的 このソフトウェアの目的
- 要求仕様 要求仕様書、機能仕様書などへのリンク（要求仕様の要点を書く場合もある）SLI,SLO
- 背景 このソフトウェアを開発する背景・経緯など
- 既存のものとの相違点 既存品があるなら、それとの違いを書く
- 関連システム・仕様など 関連システムやその仕様書へのリンク
- ハイレベルアーキテクチャ（アーキテクチャ概要） システム全体を俯瞰した構成図など
- 各パート（モジュール・クラス）の概要 各パートの概要・責務・目的など
- 各パート（モジュール・クラス）の内部仕様・処理フローなど データ構造、アルゴリズムなど
- 各パート（モジュール・クラス）の実装場所 ソース・ファイル名、実行形式の名称など
- 使用例 モジュールの利用例が分かるサンプルコードなど
- セキュリティ仕様・考慮事項など 想定される問題と、その対処方法などについて
- 既知の問題 事前に判明している問題・課題などを書く
- テスト方案 どういう観点で何をテストすればよいか、どのようにテストすればよいか
- 運用方法 運用時のポイント、監視の方法など
- 参考文献 参考文献へのリンク
- このDocの格納場所 リポジトリのパス、ファイルサーバのパスなど
- メモ 設計のヒントや気付いた点、関連情報など何でも
- 変更履歴 このDocについて、いつ・誰が・どのような変更をしたのか履歴を記述
想定読者は基本的には他のプログラマであり、誰かに納品するようなものではない。
READMEとの共存
readmeではもう少し実装よりの情報を載せるほうが良いかもしれない。
- 開発環境
- デプロイ
- モニタリング
- design docへのリンク
amazonの場合
ちょっと古い情報ではあるんだけど、まずプレスリリースを作ってしまうらしい。
- 見出し 顧客が商品を理解できるタイトル
- 副題 ターゲット層と、彼らのメリットを1行で。
- 概要 商品の特徴と利点をまとめる。この段落で全てを理解できるように。
- 課題 このプロダクトが解決する課題を説明。
- 解決 プロダクトがどのように課題を解決するかを説明。
- コメント 自分による紹介コメント（社長のコメント的なもの）。
- 使い方 どれくらい使い方が簡単かを説明。
- ユーザーからの声 仮想ユーザーからのコメント。
- 締め 最後にしめ、次にユーザーがどうすればいいかを示す