本当にユーザーに読まれるリリースノートを書くための実践的な方法
1分で読めます 更新
読まれるリリースノートを書くには、各項目でたった一つの質問に答えればいい。読者が今できるようになったことは何か、そしてそのために何をする必要があるのか。期限があるものは必ず先頭に置き、対象者を明示し、本当に何もする必要がなければ「対応不要です」とはっきり書き、何も語ることのないリリースは省略する。このページの残りはすべて、この一つのルールを具体的に当てはめたものだ。
バグ修正とパフォーマンスの改善。
どの製品も一度はこれを公開したことがあるはずだ。原因はほとんどの場合、怠慢ではない。これは、二週間もdiffに没頭して、もう部外者がどこに関心を持つのか見えなくなった人が、内側からリリースノートを書いたときに起こることだ。もっと良い文体にしても解決しない。質問に答えることが解決する。
リリースノートに何を含めるべきか
言及に値する変更ごとに、リリースノートには次を含めるべきだ。読者が今できるようになったこと、誰に影響するか、何をする必要があるか（「何もない」を含む）、そして期限があるものはいつ発効するか。含めるべきではないのは、社内のチケット番号、チームだけが使うコンポーネント名、そして唯一の見出しとしてのバージョン番号だ。
| 含めるもの | 省くもの |
|---|---|
| 読者の言葉での結果 | チームの言葉での実装 |
| プラン、役割、APIバージョンごとの対象者 | 「一部のユーザー」 |
| 必要な対応、または「対応不要です」 | 読者が最悪のシナリオで埋める沈黙 |
| 期限があるものすべてに対する日付 | 日付の代わりのバージョン番号 |
| 説明するドキュメントへのリンク | プルリクエストへのリンク |
| 報告されたバグと引き上げられた制限 | 社内のチケットID |
| 一行ずつの地味なセクション、末尾に | ニュースと混ざった地味なセクション |
リリースノートとチェンジログのエントリの分離が、このリストを可能にしている。チェンジログはすべてを保持するので、ノートは何かを省略してよい。変更の種類ごとの注釈付きのサンプルはリリースノートの例にまとめている。
すべての項目が答える質問
読者が今できるようになったことは何か、そしてそのために何をする必要があるのか?
これに答えられない項目は、リリースノートではなくチェンジログに属する。両方の半分が重要だ。前半は価値そのもの。後半はチームが忘れがちな部分であり、それが欠けたときにサポートチケットを生む部分でもある。
実際に機能している後半の二つの例：
- 「既存のWebhookは11月1日まで動作し続けます。それ以降は、署名のないペイロードは拒否されます。」
- 「対応不要です。既存のエクスポートは、次回開いたときに自動的に再エンコードされます。」
二つ目は「対応不要です」と明示的に述べている。この一文は毎回書く価値がある。それを見つけられない読者は最悪の事態を想定するからだ。
リリースノートはどう並べるべきか
システムのどの部分が変わったかではなく、読者への影響順に並べる。API、ダッシュボード、モバイル、インフラで分類するのは自分たちの組織図であって、読者の問題ではない。
- 破壊的変更と期限のあるものすべて。 どんなに小さくても常に最初に。読者が一行読んで読むのをやめるなら、それがまさに読んでおくべき一行であるべきだ。期限がサンセットなら、その項目は非推奨化の通知のように読めるべきだ。
- 新しくて求められているもの。 段落ごとに一つ、結果を最初の一文に。
- 改善されたもの。 報告されたバグ、引き上げられた制限、遅かったもの。
- その他すべて、リストとして。 依存関係の更新、内部のリファクタリング、細かなコピー。それぞれ一行ずつ。このセクションは誰も読まないが、それでも存在すべきだ。探している人には本当に必要だからだ。
書き直し
前：
v4.2.0 負荷時に
POST /exportsエンドポイントが断続的に500を返す問題を修正。エクスポートワーカーをリファクタリング。node-pgを8.11に更新。CSVシリアライザのエラー処理を改善。
後：
大規模アカウントでエクスポートが失敗しなくなりました。 約50,000行を超えるアカウントは、特に月末にエクスポートを開始すると500エラーになることがありました。これは修正され、どのサイズのエクスポートも失敗せずに自動的に再試行するようになりました。対応不要です。先週失敗したエクスポートは、単に再実行するだけで大丈夫です。
4.2.0ではさらに：
node-pg8.11、CSVシリアライザのエラーがより明確に。
同じリリース。二つ目は影響を受けたアカウント、最も悪化した時期、何が変わったか、何をすべきかを明示している。依存関係の更新は消えたわけではなく、見出しであることをやめただけだ。リリースノートのベストプラクティスの記事には、この書き直しが従う残りのルールが、それぞれ省略した場合のコストとともに掲載されている。
削除する価値のあるもの
- 「発表できることを嬉しく思います。」 読者はまだ嬉しくない。その気持ちは次の文で勝ち取るべきだ。
- 社内のチケット番号。
PROJ-4471はあなたのトラッカーの外では何の意味も持たない。参照が必要なら、ドキュメントページへリンクする。 - 自分のチームだけが使うコンポーネント名。 「取り込みパイプライン」を改名したなら「インポート」と言う。
- 唯一の見出しとしてのバージョン番号。
v4.2.0はアーカイブ用のラベルであり、要約ではない。 - 誰も訪れない設定ページのスクリーンショット。 変わったものを、使われている状態で見せる。
リリースノートはどのくらいの頻度で公開すべきか
スケジュールではなく、何かが起きたときに公開する。毎回のリリースで届くノートは、全員にそれを無視することを教え込む。何かが起きたときに届くノートは開かれる。ノートを一切付けずにリリースし、その項目を、読む価値のある見出しを持つ次のセットに転がしてしまうのは問題なく、たいてい正しい判断だ。
チェンジログはすべてを記録し続ける。それが役割分担だ。チェンジログは完全であり、ノートは選択的である。チェンジログを常に構造化して維持していれば、ノートを書くことは考古学ではなく選定と書き直しになる。
リリースノートのテンプレートは、選定の段階で使う形式であり、チェンジログの例は、そこからノートを導き出せるほど質の高いチェンジログを持つチームの項目を集めている。
ここまでの話はすべて、完全にコントロールできるページ、長さの制限がなくリンクが機能するページを前提としている。モバイルアプリのリリースノートは、面がApp StoreやPlay Storeの掲載情報になったときに何が変わるかを扱っている。 緊急リリースノートはもう一つの例外を扱っている。通常の 執筆プロセスにまったく従う時間が残っていないときに何が変わるかだ。
公開前の一つのテスト
二週間休暇を取っていて、40秒しかない人としてノートを読んでみる。その時間で、何かが自分に求められているかどうかを判断できないなら、そのノートはどれだけ正確であっても未完成だ。
FAQ
リリースノートはどのくらいの長さにすべきか? 結果を伴う変更が必要とする長さだけ、それ以上は一行も書かない。破壊的変更一つと改善二つのリリースなら三段落だ。地味なリリースを重要そうに見せるために水増しするのは、読者がノートを読み飛ばすことを学ぶ原因になる。
リリースノートは誰が書くべきか? 変更を理解している人が書き、それを理解していない人が編集する。エンジニアは何が変わったかを知っている。編集者は部外者が何を誤解するかを知っている。エンジニアがまだ記憶しているうちに、マージのタイミングで項目を書くことが、これを安く済ませる実践方法だ。
リリースノートにバグ修正を含めるべきか? 含めるべきだ、誰かが報告したり遭遇したりしたものは。原因ではなく、読者が見た症状を述べる。「50,000行を超えるエクスポートが失敗していた」は読者が認識できる修正だが、「エクスポートワーカーのレースコンディションを修正」はコミットメッセージだ。
リリースノートとチェンジログの違いは何か? チェンジログは完全で継続的な記録であり、リリースノートは一つのリリースについて選定されたメッセージで、関心があるかまだ決めていない人々に向けて書かれている。より長い答えはチェンジログ対リリースノートにある。
この記事の技術的な記述は第三者による確認を受けていません。誤りがあればお知らせください。修正します。