読まれる release notes の書き方

読まれる release notes の書き方は、ユーザーに見える変更を1件1項目にし、読者が新しくできるようになったことを最初に置き、バージョンと日付を決まった1行にまとめ、詳細は1つのリンクだけにする、という順番です。エレベーターの中で読み切れる長さにします。短く書きます。release notes はお知らせであり、2つ目の変更履歴ではありません。

多くの release notes が失敗する理由は地味です。チームがやったことを、やった順番で、チーム内部の呼び名を使って書いてしまいます。読者が知りたいのは1つだけです。昨日できなかったことが、今日できるようになったのか。そこに向けて書けば、形式はほぼ自然に決まります。

release notes が変更履歴に寄っていく理由

変更履歴は積み重なる記録です。release notes は1つのバージョンに添える短いお知らせです。同じデプロイのあとに、同じ人が、同じチケット一覧から書くので混ざります。一覧がそのまま構成になると、お知らせは実装日記になります。

Keep a Changelog はこの違いを1行で書いています。変更履歴は機械のためではなく人のためのもので、コミットメッセージを流し込むのは変更履歴ではない、という考えです（keepachangelog.com、2026-10-18 参照）。同じ判定は release notes にも使えます。サービスの内部名を知っている人にしか通じない項目は、まだ読者に出す準備ができていません。

ユーザーに見えない変更は、たいてい変更履歴に置き、release notes には入れません。

release notes の4つの要素

ユーザーに見える変更は、次の順番で4つの問いに答えます。何が変わったか、誰に関係するか、読者は何をすればよいか、詳細はどこにあるか。最初の2つはそれぞれ1文です。3つ目は「何もしなくてよい」で終わることも多く、それで問題ありません。4つ目はリンク1つで、説明の段落は付けません。

この順番は読み飛ばし方に合っています。各行の最初の数語を見て、自分に関係しそうな行で止まり、そこで初めてクリックするかを決めます。「課金サービスのリファクタリングを行いました」から始まるお知らせには、止まる理由がありません。

そのまま使えるテンプレート

成果物はこの1ブロックです。固定のヘッダーを上に置き、変更ごとに1ブロック書きます。読者が形式に慣れているならラベルは消してもかまいませんが、順番は変えません。

## 2026-10-18 · v1.4.0

**新規**
- 製品プロフィールを CSV で書き出せます。すべてのプランで利用可能。有効化は不要です。
  詳細: /help/export-product-profile

**改善**
- ディレクトリへの送信で、最後に確認した日付を保持するようにしました。操作は不要です。

**修正**
- ページを再読み込みしても、ローンチチェックリストがリセットされなくなりました。

**必要な操作**
- 10月1日より前に独自ドメインを接続した方は、DNS レコードを再確認してください。
  詳細: /help/custom-domain

テンプレートを実運用で保たせるルールは2つです。バージョンと日付はヘッダーにだけ書き、各行には繰り返しません。各項目はコンポーネント名ではなく、読者ができることから始めます。「製品プロフィールを CSV で書き出せます」は通ります。「CSV エクスポーター v2」は通りません。

入れるもの、入れないもの

判断は変更の種類で行い、差分の大きさでは決めません。読者に見えるものを変える1行の修正は入れます。見た目が何も変わらない1週間の内部作業は入れません。

価格の変更は、画面ではなく判断を変えるので、独立したお知らせにします。箇条書きに埋めると見落とされ、そのあとのサポート対応のほうが追加のお知らせより高くつきます。

セキュリティは判断が必要です。何をすべきか、どのバージョンが影響を受けるかは書きます。修正が全員に行き渡る前に再現手順を公開してはいけません。2つ目を安全に書けないなら、書く量を減らし、公式の注意書きへリンクします。

1つの release notes を複数チャネルで使う

1回書き、容器だけを変えます。事実は変えません。変更履歴ページは全項目を残します。アプリ内のお知らせは現在の画面に関係する項目だけにします。メールは判断を変える1項目だけにします。ディレクトリやコミュニティの投稿は、文脈なしで新しい読者に通じる1項目だけにします。

ここで「本当のこと」が2つ生まれがちです。日付とバージョン番号はどこでも同じにします。変更履歴が「v1.4.0 は10月18日公開」と書いたら、メールは日付をどこかに入れずに「今週」とだけ書くわけにはいきません。

release notes が壊れる場所

失敗は予測でき、どれにも見える症状があります。

1. コミットログになる。症状はサービス名、ブランチ名、チケット番号が出ること。読者の画面から逆に書き直します。
2. 毎回「画期的」になる。症状は毎月同じ3つの形容詞。形容詞を消し、動詞を残します。
3. サポート窓口より遅れて届く。症状は公開前に「なぜ変わったのか」と聞かれること。バージョンと同時に出します。

見つけにくい4つ目もあります。誰も見つけられない変更をお知らせすることです。新機能が3階層のメニューの奥にあり、お知らせが場所を書いていなければ、内容は正確でも役に立ちません。経路を書くか、スクリーンショットを足すか、経路を示すページへリンクします。

測っていないこと

私たちは、より良い release notes が継続率やアップグレード、サポート量を変えるかどうかを測っていません。その効果だけを取り出した検証可能な公開研究も見つけていませんし、数字を作るつもりもありません。言えるのはもっと狭いことです。読者の順番で書いたお知らせは読み飛ばしやすく、「必要な操作」の行がある項目は「で、何をすればいいの」という返信を減らします。これは執筆上の判断で、測定結果ではありません。

よくある質問

release notes はどのくらいの長さが適切ですか

ユーザーに見える変更に見合う長さで、それ以上ではありません。1件なら3行でも足ります。10件でも、各項目が1文なら1画面に収まります。目次が必要なら、それはお知らせではなく変更履歴ページでしょう。

デプロイのたびに書く必要がありますか

いいえ。読者が気づくリリースごとに書きます。見える変化がないデプロイには不要です。ボタンの文言を変えたデプロイには必要です。誰かが気づき、自分の記憶を疑うからです。

SEO や AI の回答に効きますか

効く可能性はありますが、「release」という語のせいではありません。日付があり、機能名、対象プラン、操作が書かれたページは、あとからその機能名で検索する人にとって有用な着地点になります。機能名のないバージョン番号だけのページは、検索エンジンにほとんど材料を与えません。引用の増加は測っていないので、これは構造上の理由であって約束ではありません。

どこに置くのがよいですか

バージョンごとに1つの正規 URL を置き、日付をページに、可能なら URL にも入れます。短い版は必要なチャネルへ転載してかまいませんが、リンクの着地点は正規ページのままにします。同じ文面を5か所に、5つの違う日付で置くと、真実の出どころが5つになります。

次の一歩

直前に出したリリースから1項目を選び、4つの要素の順番で書き直してください。短く具体的になったなら、テンプレートは機能しています。逆に長くなったなら、できることではなく実装を説明している可能性が高いです。

release notes はコンテンツ制作の入り口の1つです。同じ「読者から書く」直し方は、ライターに渡すコンテンツブリーフにも、製品紹介をチャネルごとに作り直すときにも当てはまります。お知らせができたら製品のある場所で公開し、コンテンツ制作の流れを1か所にまとめておけば、次のリリースが白紙から始まりません。