ドキュメントの心得

1.完璧なドキュメントを書かない

ドキュメントは過多になっても過少になってもいけない。


・ドキュメント過少
　全てを覚えておくことは不可能。
　また、メンバ間で情報を伝える際にも内容が伝わりにくく、効率が悪い。
　そのため、たとえメモ程度でもあったほうがよい。


・ドキュメント過多
　概略から詳細まで全てを同一文書内に共存させると、
　何が言いたいのか、どこに必要な情報が記載されているのかがわかりにくくなる。
　また、設計時に実装レベルの細かな記述を書くと実装時にブレが生じてしまい、
　ドキュメントを修正しなければならなくなる。
　ドキュメントを完璧に仕上げるのはソフトが完成してからでよい。
　それまでは必要最低限の情報を書き、不明瞭な点やToDoは別に管理する。

・自画自賛
一生懸命努力するのはよいことだが、
完成度の高いものを目指しすぎてドキュメント作成をしてしまうと、
その後の修正発生などでモチベーションが低下してしまうことがある。
そのため、完璧なドキュメントを求めるのではなく、
進化の過程であると意識して、進化しやすいドキュメントを作成する。

2.ドキュメントの共同所有

流れ
(1)ドキュメント作成
(2)公開
(3)ドキュメント修正
(4)確認
(5)(3)、(4)の繰り返し
上記の作業をメンバ全員が行えるようにする。
ただし、担当者以外が修正をする際は、「誰が」「何を」修正したかを報告する。

ドキュメントのライフサイクル

・維持ドキュメント
システムに同期して修正が必要なドキュメント

e.g)要件定義書、データベース定義書、操作手順書、テスト仕様書


・一過性ドキュメント
一度書いたらあまり修正されないドキュメント

e.g)各種検討資料、課題管理書、議事録

---

「プロジェクトの価値や優先度基準」をメンバ全員で共有できれば、
コミュニケーションのロスが少なくなり、統一されたシステムをつくりやすい。
そのためにも”なぜ”を抑えることは重要であるが、それは一過性ドキュメントに多く現れる。

維持ドキュメントに”なぜ”を盛り込むことも可能だが、
冗長になり目的がぼやけてしまう可能性がある上にコストもかかるので、
一過性ドキュメントと維持ドキュメントを分けてドキュメント化することが重要である。