Open1

ドキュメント駆動開発

前提

  • ドキュメント=仕様書ではない
  • ミドルウェア製品を開発
  • 小さなチーム
  • パッケージ製品
    • そのため顧客に提供する製品ドキュメントが必ず必要
  • GitHub を利用
  • git-flow を採用

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

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

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

  • 作りたい機能をぼんやりでいいので GitHub Issue に追加する
  • 依頼したい部分の製品ドキュメントを書く
  • 依頼する

なぜ開発と平行して製品ドキュメントを書くのか

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

デメリット

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

ドキュメント作成

  • リポジトリに含めるデザインドキュメントは reStructuredText を利用
  • 顧客に提供する製品ドキュメントは Sphinx と独自テーマを利用
作成者以外のコメントは許可されていません