資料を書くときのルール
前に会社で整理して忘れてしまったが思い出してまとめておく。
- 読み手の動機を意識した資料を書く
- 「自分が何を伝えたいのか」ではなく「相手がなぜ知りたいのか」を意識する
- 独りよがり自重
- 技術資料の主な動機パターン、どのパターンのための資料か?
- 新規メンバーの立ち上げに利用する
- 「メンバーに追いつきたい」「理由はいいから、今どうなっているのか知りたい」
- What(事実)/Where(位置) 指向で書く
- レビューに利用する
- 「何が問題なのか」「どうしてそれを選択したのか」
- Why(動機)/How(選択) 指向で書く
- 派生開発などの計画立案に利用する
- 「この機能に関係するモジュールはどれか」
- Where(位置) 指向で書く
- 新規メンバーの立ち上げに利用する
- How の書き方(対処法を書くことは How ではない)
- How は原則「他にどんな方法があって、なぜそれを選択したか」に応えて「なるほど」と思わせなければいけない
- 「課題とその対処を明示しただけ」は、最後の結果しか書いていない数学の回答と同じで、読み手の更なる疑問がわくだけ
- 「なるほど」を伴わないのは How ではなく、What (事実)
- ソフトウエアは性質上、手続きの集合なので、How と What の境界が曖昧になりやすい
- レビューに必要な How は、解決方法(事実)の提示ではなく、選択の合理性の説明