Open1
ドキュメント駆動開発
前提
- ドキュメント=仕様書ではない
- ミドルウェア製品を開発
- 小さなチーム
- パッケージ製品
- そのため顧客に提供する製品ドキュメントが必ず必要
- GitHub を利用
- git-flow を採用
自分で開発する場合のフロー
- 作りたい機能をぼんやりでいいので GitHub Issue に追加する
- feature ブランチを切る
- デザインドキュメントをリポジトリの doc/ 以下に書く
- デザインドキュメントに合わせてコーディングを進めてなんとなく動くところまで作る
- デザインドキュメントは書き捨て前提
- 製品ドキュメントを書き始める
- ブランチマージに向けてコーディングを進める
- 書ける範囲でテストを書く
- ドキュメントを平行して修正する
- プルリクエストをだしてレビューへ
- 問題なければマージ
- GitHub Issue を閉じる
- この時点で開発した機能の製品ドキュメントは完成している
- 製品ドキュメントのリリースノートも更新されている
開発を依頼する場合のフロー
- 作りたい機能をぼんやりでいいので GitHub Issue に追加する
- 依頼したい部分の製品ドキュメントを書く
- 依頼する
なぜ開発と平行して製品ドキュメントを書くのか
- 最初に大まかなデザインドキュメントを書く事で頭が整理される
- 本当にこの機能が必要なのかどうか議論しやすい
- 製品ドキュメントとコードを行き来することで設計が整理されていく
- 人に伝えにくい機能は使って貰いにくい
- 製品ドキュメントが書きやすい事はとても重要
- 検証や SDK 側対応などが必要になるため、製品ドキュメントが無いと困る
- 機能を思い出しながらドキュメントを書くのは辛い
- 開発中が一番その機能を理解している
- 一人で仕事してるわけではないので、情報共有を円滑にするため
- この開発方法をとっていると、周りがとりあえず製品ドキュメントを読むという習慣が付く
- 機能追加とともに製品ドキュメントも完了する
- リリース前に製品ドキュメントが終わらないが無くなる
デメリット
特に今のところ感じたことは無い。
ドキュメント作成
- リポジトリに含めるデザインドキュメントは reStructuredText を利用
- 顧客に提供する製品ドキュメントは Sphinx と独自テーマを利用
作成者以外のコメントは許可されていません