ドキュメント駆動開発

前提

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

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

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

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

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

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

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

デメリット

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

ドキュメント作成

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