Open1

ドキュメント駆動開発v2

voluntasvoluntas

前提

ここで言っているドキュメントは仕様書ではなく、顧客向け製品ドキュメント。

  • ミドルウェア製品を開発
  • 小さなチーム
  • パッケージ製品とパッケージ製品のクラウド版
    • そのため顧客に提供するドキュメントが必ず必要
  • 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

  • 仕様書は?
    • デザインドキュメントがよく言われる内部向けの仕様書になる
  • 内部実装の齟齬が出たりしないの?
    • デザインドキュメントとコードレビューで潰す
  • テスト駆動とどう違うの?
    • テスト駆動はコードを評価する、ドキュメント駆動は顧客向けの製品として評価する、全く別物と認識している