ドキュメント駆動開発v2

前提

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

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

自分で開発する場合のフロー

• 作りたい機能をぼんやりでいいので GitHub Issue に追加する
• feature ブランチを切る
• デザインドキュメントをリポジトリの doc/ 以下に書く
• デザインドキュメントに合わせてコーディングを進めてなんとなく動くところまで作る
  • 動かなくてもいいのでイメージを膨らませるためにコードを書いてみる
  • デザインドキュメントは書き捨て前提で、とにかくメモを書く
• 製品ドキュメントを書き始めて、一旦書き終える
• ブランチマージに向けてコーディングを進める
• 書ける範囲でテストを書く
• ドキュメントを平行して修正する
• プルリクエストをだしてレビューへ
• 問題なければマージ
• GitHub Issue を閉じる
• この時点で開発した機能の製品ドキュメントは完成している
  • 製品ドキュメントのリリースノートも更新されている

開発を依頼する場合のフロー

• 作りたい機能をぼんやりでいいので GitHub Issue に追加する
• feature ブランチを切る
• デザインドキュメントをリポジトリの doc/ 以下に書く
• デザインドキュメントに合わせてコーディングを進めてなんとなく動くところまで作る
  • 動かなくてもいいのでイメージを膨らませるためにコードを書いてみる
  • デザインドキュメントは書き捨て前提で、とにかくメモを書く
• デザインドキュメントをベースに開発担当者と認識合わせや議論をする
• 製品ドキュメントを書き始めて、一旦書き終える
• 依頼する
• 開発担当者からのフィードバックでドキュメントを修正していく
• プルリクエストをだしてもらってレビューへ
• 問題なければマージ
• GitHub Issue を閉じる
• この時点で開発した機能の製品ドキュメントは完成している
  • 製品ドキュメントのリリースノートも更新されている

なぜ先行して製品ドキュメントを書くのか

• 最初に大まかなデザインドキュメントを書く事で頭が整理される
  • 本当にこの機能が必要なのかどうか議論しやすい
• 製品ドキュメントがあり、開発時のフィードバックで設計を整理できる
  • 人に伝えにくい機能は使って貰いにくい
  • 製品ドキュメントが書きやすい事はとても重要
• 検証や SDK 側対応などが必要になるため、製品ドキュメントが無いと困る
• 機能を思い出しながらドキュメントを書くのは辛い
  • 設計中が一番その機能を理解している
• 一人で仕事してるわけではないので、情報共有を円滑にするため
  • この手法をとっていると、周りがとりあえず製品ドキュメントを読むという習慣が付く
• 機能追加とともに製品ドキュメントも完了する
  • リリース前に製品ドキュメントが終わらないが無くなる

デメリット

特に今のところ感じたことは無い。

GitHub Copilot や ChatGPT (GPT-4) の影響

• GitHub Copilot は日本語も提案してくれるのでドキュメントを書くスピードが上がった
• ChatGPT で日本語の読みやすさを提案などをしてもらえるようになった

ドキュメント作成

• リポジトリに含めるデザインドキュメントは reStructuredText を利用
• 顧客に提供する製品ドキュメントは Sphinx と独自テーマを利用
  • https://sora-doc.shiguredo.jp/

FAQ

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