全てのドキュメントに書くべき事項・決めるべき運用ルール
良いドキュメントを書くために、必ず書くべき事項、必ず定めるべき運用ルールの定石を紹介する。
目次
全てのドキュメントに書くべきヘッダ
- タイトル
- 何のためのドキュメントであるかを一言で伝える。名前重要
- 何が書いてあり、何が書いてなさそうかを一言で伝える
- 成果物 ID
- 「成果物一覧」と比較して、納品時に過不足がないか確認できるようにするため
- 納品しないドキュメントの場合も、「どのドキュメントについて話しているか」をチーム内で明らかにするため、何らか一意になる ID を設けておくと良い
- 初版作成日
- いつ頃作られたドキュメントか分かる → そのドキュメントが作られた起因を後で追いやすい (作成日の少し前に作成 or 更新されたドキュメントを見つけやすくなると、経緯も追いやすい)
- 初版作成者
- 誰が作ったドキュメントか分かる → ドキュメントの内容に関して質問したいことがある時、相手が分かる
- 最終更新日
- 最後に更新された日付が分かる → きちんとメンテナンスされているドキュメントか、放置されているドキュメントかの区別が付く
- 放置されているドキュメントは情報の鮮度が悪く、「誤りになった」情報を含んでいる可能性が高いので、信頼性に欠ける。読む時に鵜呑みにしないつもりで読みやすい
- 最終更新者
- 最後に更新した人が分かる → 最後の更新内容に関する質問がある時、相手が分かる
全てのドキュメントで個別に定めておくべきルール
- 記載範囲
- そのドキュメントに何を記載して、何を記載しないか、を明記する
- (一見関連しそうだが) そのドキュメントに記載しないことにした事柄については、代わりにどこで説明しているか、関連ドキュメント名やリンクを記しておく
- ex. この画面仕様書は、「○○」画面の仕様を記す。「○○」画面と対になる「○○」帳票の仕様については記載しない。別途「○○帳票仕様書」を参照のこと
- 更新の要領
- そのドキュメントをどういうタイミングで、どのように更新して良いか。更新時の禁止事項があれば明記する
- ex. 仕様変更が発生した場合は、当該箇所の旧文言を「更新履歴」シートに転記しておく。そのうえで、修正した文言は赤字に設定する
- そのドキュメントをどういうタイミングで、どのように更新して良いか。更新時の禁止事項があれば明記する
- 削除・凍結の要領
- そのドキュメントが必要なくなる (ファイルごと削除しても良くなる) タイミングがあれば、それを明記する削除する。予定がない場合も、その旨を明記する
- ex. この「検討事項一覧」資料は、一覧に挙がった内容全てが「要件一覧」もしくは「課題一覧」に転記された後は、不要になる (削除しても良い)
- ex. この画面仕様書は、改修の度に更新し続けていくため、システム自体が廃止されるまで削除してはならない
- ファイルごと削除しないまでも、それ以降更新しなくなるタイミングがあれば記載する
- ex. この「設計課題一覧」は、設計フェーズが完了した時点で凍結し、以降は更新してはならない。未完了の課題が残った場合も、本ファイルは更新せず、実装フェーズにて「実装課題一覧」に転記し運用する
- そのドキュメントが必要なくなる (ファイルごと削除しても良くなる) タイミングがあれば、それを明記する削除する。予定がない場合も、その旨を明記する
テンプレート
分かりやすく、抜け漏れのないドキュメントを効率良く書くためのテンプレートを作りました。以下よりダウンロードして参考にしてください。