第11章：ドキュメント品質の守り方（陳腐化対策 / Owner / KPI）
この章で学ぶこと
- 陳腐化は発生する前提で検知手段を設ける
- Owner と期限（棚卸し）で更新を回す
- 量ではなく有用性/更新性の KPI を検討する
- 再確認条件を明示し、文書が古くなる前に見直しを起動する
この章の成果物（または判断基準）
- 棚卸しルール（期限 / Owner / 更新）
- 品質 KPI 案（有用性、更新性、事故削減への寄与）
- 文書保守カード（Owner、見直し日、再確認条件、更新先）
本文
品質は「書いた直後」ではなく「半年後」に差が出る。運用される文書にするには、Owner と見直し期限が必要。
陳腐化の検知
- 期限（見直し日）
- 変更履歴の空白
- 事故/問い合わせの増加
- 依存サービス、外部仕様、組織体制、連絡先の変更
- PR / Issue のレビューで同じ質問が繰り返される
文書保守カード
重要な README、Runbook、ADR、ポストモーテム、監査メモには、本文末尾または管理表に保守カードを持たせる。
| 項目 | 書き方 |
|---|---|
| Owner | 棚卸しと更新判断の責任者。個人名だけでなくチーム名も併記する |
| 最終確認日 | 最後に本文・リンク・手順・連絡先を確認した日 |
| 次回見直し | 定期棚卸し日。重要 Runbook は短め、ADR は変更契機ベースでもよい |
| 再確認条件 | 外部仕様変更、障害再発、問い合わせ増加、担当チーム変更など |
| 更新先 | PR、Issue、Runbook、ADR、監査メモなど、どこに証跡を残すか |
保守カードは「全ドキュメントに重いメタ情報を付ける」ためではない。古くなると事故や誤判断につながる文書に限定し、最小項目で運用する。
ありがちな破綻パターン
- ドキュメント孤児（入口がない）
- 手順の腐敗（実行すると失敗する）
- Owner 不在（誰も直さない）
具体例（悪い例→良い例）
悪い例
文書はあるが、更新されない
問い合わせが増えても放置
良い例
Owner を決め、見直し期限を設定
問い合わせ/障害を起点に手順を更新
KPI を「更新性/有用性」で見る（量で評価しない）
チェックリスト
- Owner が明確
- 見直し期限がある
- 入口（README / 目次）から辿れる
- 事故/問い合わせを更新に反映している
- 再確認条件が明確
- 更新先（PR / Issue / 監査メモ）が決まっている
まとめ
- 陳腐化を前提に、Owner と見直し期限で更新を回す
- KPI は量ではなく、有用性/更新性（問い合わせ/事故削減への寄与）で設計する
- 再確認条件と更新先を決め、文書が古くなる前に見直しを起動する
次章への接続
- 付録: テンプレ集