継続して提供されるサービスであれば、仕様や意思決定の経緯を残したい。
どういう形ならあとからそれらを辿れるかなあというのを考えてるメモです。中身はあまりない。
イメージしてるのはこんな感じ。
要求仕様・機能要件
開発アイテムが発生した際に書くドキュメント。
ステークホルダーと合意した要件やその案件で満たすべき仕様を記述する。
対外的に機能紹介をするときにここだけ読めば伝わる状態だと良い。
親ページにはおおまかに下記が書いてあって、関連する小ページへのリンクを貼る。
- ペルソナ
- やること・やらないことのスコープ
- デザイン
- 開発範囲の外部仕様
- 画面上の挙動や制約、注意点など
設計ドキュメント
内部的な設計資料がぶらさがってるイメージ。
テーブル設計や各種リソースの構成図、APIのIFなど。
議論が発生した場合は議事録側にメモを残し、リンクされているとよい。
文字数とか操作の制約とかがあればなぜなのか書いてあるとうれしい。
調査ドキュメント
機能開発や設計において調査した結果のメモ。
行った調査や意図が記録されていてほしい。
議事録
部署間のMTGからチーム内の議論まで、「案件に関わる意思決定」に関連する会話のメモ。
参加者、会話内容、意思決定、もしあれば次のアクションアイテムが書かれていると良い。
仕様書
機能が開発されたあと継続してメンテされていくドキュメント。
追加開発や改修が発生した際は開発完了時にこのドキュメントに反映される。
文言や分岐、各種バリデーションとかエラーとかが網羅されていてほしい。
更新フロー
開発中は常時意思決定や設計ドキュメントが更新され、開発完了時にそれらの差分が機能ドキュメントに反映されてほしい。
更新時は相互にリンクされてると最高。
ここまで書いて思うこと
自分はドキュメントを書くのが苦ではない方なので困らないけど、あんまりドキュメント書かないタイプの人に全部書いてっていうと嫌がられる。
仕様として残す範囲の挙動も個人に依存しそうで、かといってガチガチにすると多分メンテされなくなる。
そもそも単機能が肥大化してしまっている場合、この形ではおそらく記述しきれないし、複数ラインで同じ機能の開発が走ったときに開発中機能の仕様記述がコンフリクトしそう。
細かい仕様はどこまで残すのかとかも含めて何もわからん。
そもそもすでに機能があるけどドキュメントがないみたいなときどうする問題もある。
こういうドキュメンテーションがうまくいってる事例をもっと知りたい。
