リリースノートとは、ソフトウェアのリリース時に機能や目的などを知らせるための資料であり、ソフトウェアがアップデートされる場合も機能強化や不具合修正に関する情報をリリースノートとして公開します。リリースノートの中には優れたものもあれば悪いものもあるとのことで、「よいリリースノートを書くための10のポイント」について、ソフトウェア開発者のサイモン・ウィルソン氏がまとめています。
Writing better release notes
https://simonwillison.net/2022/Jan/31/release-notes/
ウィルソン氏は、「リリースノートはオープンソースプロセスの重要な部分です」と述べ、GitHubなどでオープンソースのプロジェクトをリリースする場合、リリースノートを適切に書くことが大切だと主張しています。最近、「よいリリースノートの書き方」について考えていたというウィルソン氏は、リリースノートを書く際の要点を以下の10個にまとめています。
◆1：リリースノートを書く
これは冗談に聞こえるかもしれませんが、ウィルソン氏は真剣だと述べています。「プロジェクトを改善するために行ってきた仕事を人々に活用して欲しい場合は、そのプロジェクトについて人々に知らせなくてはなりません！」と述べ、リリースノートを書くこと自体の重要性を訴えています。
◆2：日付を入れる
ソフトウェアリリースについてのリリースノートにしっかり日付を記載することで、ユーザーはどのバージョンが最新のものであるのかわかり、より機能が豊富で不具合が少ないバージョンを選択することができます。
◆3：バージョンごとのリリースノートへのリンクを作成する
リリースノートの末尾などに、これまでのバージョンに関するリリースノートへのリンクをまとめることも重要です。もちろん、見た人がすぐに過去のリリースノートへのリンクだとわかる形式にすることをウィルソン氏は推奨しています。
◆4：内容をヘッダーで分割する
リリースノートの内容が多い時は、「今回の新機能」「バグ修正」といった風に、トピックごとにヘッダーで分割しておくと読みやすくなります。
◆5：大事な部分を強調する
バージョンについてのあらゆる情報を盛り込んだリリースノートを作成しても、読んだ人に理解してもらえなければ本末転倒です。そのため、バージョンに関する重要な部分を強調し、わかりやすくすることが重要です。
◆6：関連ドキュメントにリンクする
リリースノートはあくまで利用者へ向けた簡潔な内容ですが、より深い情報を知りたいエンジニアらに向けて、専門的な関連ドキュメントへのリンクを付けておくと親切だとのこと。
◆7：例とスクリーンショットを活用する
ウィルソン氏は、「ほとんどのリリースノートは無味無臭なものです。リリースノートの分量に制限はないのですから、『何が変わったのか、なぜこれが重要なのか』という質問に答えるべく、自由にあらゆるツールを使ってください」と述べ、例やスクリーンショットを使ってわかりやすく説明するべきだと主張しています。
◆8：関連するスレッドへのリンクを入れる
ソフトウェア開発プラットフォームのGitHubなどを使ったプロジェクトでは、新たなバージョンの変更点に関するスレッドにリンクすることで、全体像をより把握しやすくできます。
◆9：貢献者をクレジットに記載する
誰かがソフトウェアの開発に貢献したのであれば、リリースノートのクレジットに貢献者の名前を記載し、感謝を伝えるべきです。
◆10：公開したことを人々に知らせる
せっかく新しいソフトウェアとリリースノートを公開しても、誰にも気付かれなければ意味がありません。ウィルソン氏はTwitterや個人ブログ、ニュースレターなどを通じて新たなリリースを告知しているそうで、何かしらの方法で人々に通知する必要があります。
ウィルソン氏はGitHubのリリース機能が非常に気に入っているとのこと。「あなたはタグに添付されたリリースを簡単に作成でき、各リリースにはリンク可能なページも含まれています。リリースノートはMarkdown形式で書かれ、後で編集したり、付け加えたり、入力ミスやエラーを修正したりできます」と述べています。
また、自身のプロジェクトではリリースノートに技術的な変更点を記すだけでなく、新機能に関する個人的なメモや開発に至った背景、開発で学んだこと、新機能の応用に関する意見などの注釈付きのリリースノート作成を試しているとのことです。
この記事のタイトルとURLをコピーする