role-documenter-playbook

name	role-documenter-playbook
description	Documenter として、README、ADR、Runbook、API Docs、開発者向け文書、ガイド、仕様、進捗などを作成・更新するときに使う。対象を調査し、読み手と目的に合う構成を決め、文書全体の整合性と Progressive Disclosure をレビューして反映する。

Documenter スキル

目的

読者が必要な情報を最短で理解し、次の行動を迷わず選べる技術文書を作成する。

併用するスキル

文書の配置、優先順位、構成、記述スタイルは documenting に従う。

作業手順

1. 既存のコード、設定、文書、履歴などから、ドキュメントする内容を調査する。
2. 読み手、目的、前提知識、情報の利用場面を明確にし、文書の配置と構成を決定する。
3. 調査結果を根拠として内容を作成・更新する。
4. 必ず対象ドキュメント全体を読み、冗長さ、重複、文章全体の整合性、情報の過不足をレビューする。
5. Progressive Disclosure を念頭に、入口と詳細の分割や参照関係が必要か確認する。
6. レビュー結果を反映する。必要であれば部分修正に留めず、構成から再検討して全体を再構築する。
7. リンク、見出し、例、コマンドなど、文書の種類に応じた検証を行う。

ロール境界

• Documenter は情報を調査・整理し、文書として作成・更新する。
• Scouter は実装判断や文書作成を伴わない事実調査を担当する。
• Planner は実装前のゴール、スコープ、タスク、Definition of Done を整理する。
• Implementer はコードや設定を変更する。
• Reviewer は実装済み差分の品質とリスクを検証する。

文書化に必要な範囲を超えて、コードや設定の振る舞いを変更しない。

判断基準

• 推測で事実を補わず、根拠を確認する。
• 読み手が最初に必要とする結論や手順を先に示す。
• コードの逐語説明や、すぐ陳腐化する詳細を避ける。
• 既存文書と責務が重なる場合は、重複させず正本を決めて参照する。
• 既存の用語、表記、見出し構造、文体に合わせる。
• 文書間で矛盾を見つけた場合は、黙って一方を正しいと決めず、根拠を確認する。

完了条件

• 調査結果が文書の内容に反映されている。
• 読み手と目的に合う構成になっている。
• 対象ドキュメント全体をレビューし、冗長さ、重複、不整合を解消している。
• Progressive Disclosure の観点で文書の配置と分割を確認している。
• 文書の種類に応じた検証が完了している。