SmartHR Design System

リリースノートの書き方

リリースノートを公開する目的

機能追加や不具合修正の内容など、プロダクトのアップデートの詳細をユーザーに伝えるため、リリースノートを公開します。

参考：リリースノートの定義｜Wikipedia

リリースノート(Release notes)とは、ソフトウェア製品のリリースの際に、機能強化や不具合修正の内容などをユーザーに示す資料またはウェブサイトである。 製品がすでに顧客によって利用されている場合、リリースノートはソフトウェアが更新される際に提供される。

私たちは、以下の3つの考えからリリースノートを公開してプロダクトアップデートの詳細を伝えます。

1.改善であっても、ユーザーに負荷を与えるという視点を忘れない

より使いやすくするための変更でも、プロダクトの仕様変更は、ユーザーがこれまでと同じ使い方ができなくなる変化です。
見慣れないUIがあったら、戸惑う可能性もあります。プロダクトに慣れてきた頃に、「また使い方を覚えなくてはいけない」と負担に感じるユーザーがいるかもしれません。

2.変更の意図を明確にし、新しい使い方を学習するユーザーの心理的負担を軽減したい

「なぜそのアップデートをしたのか」「どのように便利になるのか」「どう使うと便利なのか」など、開発者の意図を伝え、その必要性や意義をユーザーに理解してもらう助けになります。

3.変更内容をオープンにし続け、信頼につなげたい

より使いやすくするための変更であると説明し、ユーザーの納得感を得ることは、プロダクトを長く使い続けてもらうことにつながると考えます。

リリースノートのカテゴリ

リリースノートのアップデート情報の種類ごとに、下記のカテゴリに分類します。

新機能

  • 新規に追加した機能を記載します。
  • サービスサイトにプレスリリースやアップデート情報に関する記事を掲載している場合は、リンクも設置します。
どのように読まれるか
  • 機能が追加されて、新たに何ができるようになるのか。どんなユースケースに対応したのかを明らかにします。

改善

  • 既存の機能や画面の修正内容を記載します。
  • これまで使用時にどんな不便があったかといった経緯とあわせて、改善のために行なわれた変更を説明します。
  • SmartHR Design Systemのガイドラインに準拠するための変更の場合は、ガイドラインへのリンクもあるとわかりやすいでしょう。

どのように読まれるか

  • どの画面をどのように変更したのか、変更によって使用体験はどうなるのかを明らかにします。

不具合修正

  • 不具合の修正について、概要・件数のみを記載します。
  • ただし、ユーザー影響が大きいなど、修正内容を詳細に伝えるメリットがある場合は記載しています。

どのように読まれるか

  • 仕様上の不具合を、日々修正していることを明確にします。

アクセシビリティ

どのように読まれるか

  • アクセシビリティへの対応状況を可視化します。

廃止した機能

  • 使えなくなった機能について記載します。
  • 事前に機能の廃止をお知らせしていた、サービスサイトのアップデート情報の記事にリンクします。

どのように読まれるか

  • 機能が使えなくなったことを明示します。

リリースノートの書き方

「ユーザーがどういう風に使えるようになったか」を意識しましょう

プルリクエストとは異なり、リリースノートはユーザー目線で書き直す必要があります。
ユーザー目線 とは、評価シートの記入を終えタスクを完了するときに、［更新］ボタンを押して下書きの保存をしていなくても、［{タスク名}を終了］ボタンを押せるようになりましたというように、コード追加・修正によって生じるプロダクトの挙動ではなく、ユーザーを主語にして、何が実現されたかを書くことです。

具体的な書き方のヒント

・タイトルはユーザーへの影響が一番大きい変更を選びましょう

・見出しは要約しつつ、ユーザーが想起しやすい言葉を配置しましょう

実例

Before
「バックグラウンド処理一覧に、展開（解凍）したファイル名が文字化けしてしまった際の対応方法を載せたヘルプへのリンクを表示するようにしました」

After
「バックグラウンド処理一覧に、ダウンロードしたファイルの名前が文字化けした際の対応方法へのリンクを表示しました」

無駄な表現を削除し要約する一方、 「ダウンロードしたファイルの名前」 として、ユーザーが変更点を想起しやすくなる言葉を補います。

・主語はプロダクトではなく、開発チームを主語にして何をしたかを書きましょう

実例

Before
「各設定ページで表組みフォームに設定を一括変更するためのUIが追加されました。」

After
「表組みフォームに対して、設定を一括変更できるUIを追加しました。」

・やったことは、修正しました、追加しました、変更しましたなどと書き分け、「改善しました」という表現は避けましょう

実例

Before
「評価シート一覧ページの表示項目を改善しました。」

After
「従業員モードで表示する、評価シート一覧の列のラベル名を［進行中タスク］から［進行中タスク（期限）］に変更しました。また、［タスク担当者］の列を追加しました。」

・画面の名前はわかりやすく示しましょう

実例

Before
「各設定ページで表組みフォームに設定を一括変更するためのUIが追加されました。」

After
「評価テンプレート詳細画面のその他の設定で、表組みフォームに対して一括設定できるUIを追加しました。」

・なんらかの操作を示すときは、ボタンのアクションテキストを明記しましょう

実例

Before
「［評価テンプレート編集］の［評価ロール］では、すでに評価が開始されている評価テンプレートを編集する場合に変更が禁止されています。このとき、変更が禁止されていて何も操作することができないにも関わらず、ドロップダウンを開くことができるようになっていました。
この変更で、変更が禁止されているときは不必要にドロップダウンを表示しないように改善しました。」

After
「すでに評価が開始されている場合、取り込み済みテンプレートのうち、評価ロールは変更できません。しかし、［評価ロール］の設定画面の［操作］のドロップダウンを開くことができるようになっていました。
編集が制御されているときは不必要にドロップダウンを表示しないように修正しました。」

・UIやヘルプページの単位に表記を揃えましょう

・仕様上、制御している操作は、「禁止」ではなく「制御」や「制限」と表現しましょう

disableにしている状態を表すときは、「できない」「制限」「制御」などと書きましょう。 「禁止」には「エラーを引き起こす原因となる操作」という意味が強くその操作自体が許可されているかどうかは意図されていません。「できないように制御している状態」とは異なります。

・ユーザーの関心事の場合、変更点がないことも伝えましょう

実例

「UIのみの変更であり、検索結果や付与する権限については変更ありません。」

・「あったものを無くす」時は、きちんと意図を書きましょう

・表記は、基本的にプロダクトのライティングガイドライン、用字用語に則りましょう

以下は、覚えておきたいルールです。

  • 画面名　→　［ ］
  • 設定項目名・タブ名　→　［ ］
  • 操作ボタン名　→　［ ］
  • 設定値（ドロップダウンリストの選択肢なども含む）　→　「 」
  • カスタムオブジェクト名　→　【 】

プルリクエストのテンプレート

プルリクエスト作成時から、リリースノートを意識してコメントを書いておくと、後工程が楽になります。

参考：人事評価チームのプルリクエストのテンプレート

<!--
## 新機能
### hogeを、fugaできるようにしました
- 新機能の内容を簡潔に書く。お知らせがある場合は、詳細はお知らせのリンクに誘導するでもOK。
-->


<!--
## 改善／アクセシビリティ
### hogeを、fugaできるようにしました
* 経緯の説明
これまではfugaのため、hogeできませんでした。
［hoge］画面でfugaしたときに、piyoでしたが、hoguすると、biyoするように変更しました。


* 追加
［{画面名}］に、fugaを追加しました。


* 表示
［{ボタン名}］を押すと、hogeを表示します。


* 制御
hogeの場合には、piyoできないようにしました。


* ガイドライン準拠
SmartHR Design Systemに則ったhogeに変更
hoge、piyo、fugaなどをSmartHR Design Systemに則って変更しました。
- [コンテンツタイトル｜SmartHR Design System](URL)
-->


<!--
## 不具合修正
### {条件や画面}で{期待されている動作}できるようにしました。
{条件や画面}で{症状}できない不具合がありました。
{条件や画面}で{期待されている動作}できるようにしました。


- desk経由、 社内報告など不具合発覚の経緯についても記載しましょう。（社内向け共有用）
-->


## なぜ開発したの？


## 参考リンク
<! - チケットへのリンク -->


## キャプチャ
<!--
画面の変更がある場合は、修正前後のキャプチャを貼りつけ、
「どこ」が「どのように」変化しているのかをレビューしやすい状態にしましょう
-->
|Before|After|
| --- | --- |
| <!-- Before --> | <!-- After --> |


## やったこと


## やらなかったこと


## 確認方法