Open1
ドキュメント駆動開発v2
voluntas前提
ここで言っているドキュメントは仕様書ではなく、顧客向け製品ドキュメント。
- ミドルウェア製品を開発
- 小さなチーム
- パッケージ製品とパッケージ製品のクラウド版
- そのため顧客に提供するドキュメントが必ず必要
- GitHub を利用
自分で開発する場合のフロー
- 作りたい機能をぼんやりでいいので GitHub Issue に追加する
- feature ブランチを切る
- デザインドキュメントをリポジトリの doc/ 以下に書く
- デザインドキュメントに合わせてコーディングを進めてなんとなく動くところまで作る
- 動かなくてもいいのでイメージを膨らませるためにコードを書いてみる
- デザインドキュメントは書き捨て前提で、とにかくメモを書く
- 製品ドキュメントを書き始めて、一旦書き終える
- ブランチマージに向けてコーディングを進める
- 書ける範囲でテストを書く
- ドキュメントを平行して修正する
- プルリクエストをだしてレビューへ
- 問題なければマージ
- GitHub Issue を閉じる
- この時点で開発した機能の製品ドキュメントは完成している
- 製品ドキュメントのリリースノートも更新されている
開発を依頼する場合のフロー
- 作りたい機能をぼんやりでいいので GitHub Issue に追加する
- feature ブランチを切る
- デザインドキュメントをリポジトリの doc/ 以下に書く
- デザインドキュメントに合わせてコーディングを進めてなんとなく動くところまで作る
- 動かなくてもいいのでイメージを膨らませるためにコードを書いてみる
- デザインドキュメントは書き捨て前提で、とにかくメモを書く
- デザインドキュメントをベースに開発担当者と認識合わせや議論をする
- 製品ドキュメントを書き始めて、一旦書き終える
- 依頼する
- 開発担当者からのフィードバックでドキュメントを修正していく
- プルリクエストをだしてもらってレビューへ
- 問題なければマージ
- GitHub Issue を閉じる
- この時点で開発した機能の製品ドキュメントは完成している
- 製品ドキュメントのリリースノートも更新されている
なぜ先行して製品ドキュメントを書くのか
- 最初に大まかなデザインドキュメントを書く事で頭が整理される
- 本当にこの機能が必要なのかどうか議論しやすい
- 製品ドキュメントがあり、開発時のフィードバックで設計を整理できる
- 人に伝えにくい機能は使って貰いにくい
- 製品ドキュメントが書きやすい事はとても重要
- 検証や SDK 側対応などが必要になるため、製品ドキュメントが無いと困る
- 機能を思い出しながらドキュメントを書くのは辛い
- 設計中が一番その機能を理解している
- 一人で仕事してるわけではないので、情報共有を円滑にするため
- この手法をとっていると、周りがとりあえず製品ドキュメントを読むという習慣が付く
- 機能追加とともに製品ドキュメントも完了する
- リリース前に製品ドキュメントが終わらないが無くなる
デメリット
特に今のところ感じたことは無い。
GitHub Copilot や ChatGPT (GPT-4) の影響
- GitHub Copilot は日本語も提案してくれるのでドキュメントを書くスピードが上がった
- ChatGPT で日本語の読みやすさを提案などをしてもらえるようになった
ドキュメント作成
- リポジトリに含めるデザインドキュメントは reStructuredText を利用
- 顧客に提供する製品ドキュメントは Sphinx と独自テーマを利用
FAQ
- 仕様書は？
- デザインドキュメントがよく言われる内部向けの仕様書になる
- 内部実装の齟齬が出たりしないの？
- デザインドキュメントとコードレビューで潰す
- テスト駆動とどう違うの？
- テスト駆動はコードを評価する、ドキュメント駆動は顧客向けの製品として評価する、全く別物と認識している