説明資料の贅肉たち
顧客への説明資料の作成は難しいですね
日々感じております
最近、過去の障害について説明資料を作成したのですが、
「ちょうど良い」レベルの資料を作るのが苦手です
ついついあれもこれもと作り込みすぎるのですが、
作り込まれすぎた資料はちょっとマニアックになってしまうので
説明資料の説明が多くなってしまいます
(本末転倒ですね)
詳細なロジックまで載せるのは過剰であるため、
下記のポイントのみに絞って資料を作成しました
- 登場人物(サーバー名やプロセス名、DBのテーブル)は何か
- 正常時の挙動はどうなのか
- 障害時の挙動はどうだったのか
- 何が問題だったのか
- どうすれば解消できるのか
- 時系列で動きを追えるか
挙動を説明するときにプログラムの中身が見えるようなロジックまで書くと
資料は途端に贅肉が増えてしまいます
贅肉のないような資料作り、心がけていきたいです
