資料を書くときのルール

前に会社で整理して忘れてしまったが思い出してまとめておく。

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