人々が追い続けるチェンジログページの作り方

チェンジログページを作る価値があるのは、誰かがそこに戻ってくるだろう場合だけだ。これは単に持っているだけよりも高いハードルであり、そして多くのページが躓くのもまさにこのハードルにおいてだ。ページは存在し、フッターにリンクがあり、断続的に更新され、インシデントの最中を除けば誰にも訪れられない。この二つを分ける決定は、何かが書かれる前に下されており、多くの場合、ページがどこに置かれるか、そして同じ内容から他に何が生成されるかに関するものである。

チェンジログページとは何か

これは、製品で何が変わったかを示す、公開された日付付きのリストであり、自分が所有するURLに置かれる。同じエントリが現れうる五つの表面の一つであり、有用な問いはどれを選ぶかではなく、どれが正典であり、どれがそこから生成されるかということだ。

正典となる情報源を一つ選び、一度公開し、残りはそこから生成すること。ページとウィジェットを手作業で別々に維持するチームは、最終的に一致しない二つのテキストを抱えることになり、その食い違いは顧客によって発見される。

チェンジログページはどこに置かれるべきか

自分自身のドメイン上に、安定したパスで、各エントリがフラグメントか独自のパスによって個別にアドレス可能な形で。三つの一般的な配置は、メインサイト上のパス、サブドメイン、そしてドキュメントのセクションである。メインサイト上のパスは、それに反対する議論をすべき初期設定であり、賛成する議論をすべきものではない。サイトの権威を継承し、追加の証明書やDNSを必要とせず、ページを他のすべてと同じナビゲーションに保つ。

サブドメインが正しい答えになるのは、ページがマーケティングサイトとは別のシステムによって提供されており、そうでなければプロキシをすることになる場合だ。そのコストは、権威が別々に蓄積されることである。チェンジログをドキュメントに置くのが正しいのは、読者層が開発者である場合であり、その理由はAPIチェンジログで扱われている。読者はたいてい、すでにそこにいるからだ。

選択そのものより重要なのは、エントリが個別にリンク可能であることだ。人々はインシデントレビューや社内チケットでエントリにリンクする。「チェンジログ、下にスクロール」としてしかリンクできないエントリは、代わりにスクリーンショットとして貼り付けられることになる。

チェンジログページには何が必要か

五つのことがあり、最初の二つで多くのページが失敗する。変更ごとの日付付きエントリで、最新のものが最初に来ること。興味のあるタイプでスキャンできるよう、エントリごとのカテゴリまたはラベル。エントリごとのパーマリンク。購読の経路。約五十件のエントリを超えたら検索またはフィルタ。

残りは任意である。スクリーンショットは役に立つが、メンテナンスコストがかかる。著者名は、ある製品では信頼を築き、別の製品ではノイズになる。バージョン番号は、あるAPIの呼び出し側にとっては重要だが、それ以外のほとんど誰にとっても重要ではない。Keep a Changelogは、独自のラベルを考案する理由がなければ妥当な初期設定であり、その中心的な規則は、残りを捨てたとしても保持する価値がある。ログは人間のために書かれているという規則だ。

製品が継続的にリリースされる場合は、バージョンではなく日付でグループ化すること。「これは9日のインシデントの前だったか後だったか」をスキャンする読者は日付を探しており、バージョン番号で整理されたページは彼に計算を強いる。

ページかアプリ内ウィジェットか

両方を、一つの情報源から。ページは検索、リンク、長い記録が置かれる場所だ。ウィジェットは、ページを決して訪れないであろう大多数のユーザーに届く方法であり、それが機能するのは、彼らがすでに使っている製品の中に現れるからだ。

ウィジェットの失敗は中断である。すべてのエントリに注意を要求するバッジは一週間以内に恒久的に無視され、それは本当に重要だったエントリのためのチャネルを失わせる。読者が最後に見てからの未読数を数え、最初の訪問時には静かにカウンターを播種し、誰も一年分の履歴のバッジで迎えられないようにし、読者自身に開かせること。読者の代わりに開いてはならない。

チェンジログページを機械可読にするには

同じエントリをフィードとしても公開すること。JSON Feedは、コードでそれを消費するあらゆるものにとって最も摩擦の少ない選択肢であり、RSSフィードは、リーダーで購読する開発者が期待するものだ。エントリが手書きのHTMLではなく構造化データになれば、両方ともほとんどコストがかからない。これこそが、正典となるコピーを構造化しておくべき本当の理由だ。

ページにもマークアップを施すこと。エントリは日付とタイトルを持つ作品であり、schema.orgがその語彙を提供する。これはパーマリンクと同じ理由で価値がある。ブラウザではないもの、顧客自身のリリースプロセスを含めて、ページを利用可能にするのだ。基礎となるエントリがそもそも構造化データでなかったなら、これらのどれも機能しない。チェンジログのファイル形式は、このフィードとこのマークアップが実際に生成される真実の源として、Markdown、JSON、YAMLのそれぞれが何を犠牲にするかを扱っている。

チェンジログページはSEOに役立つか

間接的に、そしてゆっくりと。個々のエントリは、誰かが入力する検索クエリを狙っていないため、めったにランクインしない。ページは、リンクを通じてその地位を得る。エントリはサポートの返信やフォーラム、インシデント分析で引用され、それらのリンクは自分が所有するURLに蓄積される。二年間毎週更新されるページは、それが属する製品にとって信頼できる新鮮さのシグナルでもある。

機能しないのは、エントリをコンテンツマーケティングのように扱うことだ。長さのために三段落に膨らまされたエントリは、その本来の仕事、つまり自分が使っている何かが変わったかどうかを読者に一文で伝えることにおいて、より劣ったものになる。チェンジログに検索をサポートさせたいなら、パーマリンク、フィード、そこへの内部リンクに労力を注ぎ、エントリは短く保つこと。私たち自身のチェンジログの例ページは、このバランスをうまく取っているページを集めている。

人々はどう購読するのか

すでに使っている経路を与えること。開発者向けのRSSまたはJSONフィード、重要なことだけを聞きたい人向けのメール、そしてそのどちらも決して行わないすべての人向けのアプリ内ウィジェットだ。仮定するのではなく、何を聞きたいか尋ねること。破壊的変更を望んで文言修正を受け取る読者は、両方から購読解除してしまうからだ。

最後に追加すべき経路は、ループを閉じるものだ。あるエントリが特定の人が求めていたことを解決したとき、そのページを読んでくれることを期待するのではなく、直接それを伝えること。changeloopでは、エントリはページ、フィード、ウィジェットに一度に公開され、ウィジェットのフィードバックがGitHub issueになり、そのissueをプルリクエストがクローズした人は、そのissue上でエントリへのリンクとともに通知され、ウィジェットでもそのエントリを目にする。仕組みはどんな購読とも同じだが、違いは受け手がすでに尋ねていたということだ。これはチェンジログ側からフィードバックループを閉じるで展開されている議論である。

FAQ

チェンジログページはサブドメインとパスのどちらに置くべきか? 初期設定ではメインサイト上のパスにすべきだ。サイトの権威を継承し、追加のインフラを必要としないからである。サブドメインが正当化されるのは、別のシステムがページを提供する場合だ。

ページは一度にいくつのエントリを表示すべきか? 画面を埋めるのに十分な数であり、それ以上ではなく、その後にページネーションを置くこと。二年分の履歴を一つの文書に読み込むのは遅く、最新のエントリを見つけにくくする。

古いエントリはいつか削除すべきか? いいえ。それらは自分のサイトの外部から引用されており、リンクが壊れてしまう。エントリはその場でメモとともに修正し、URLは生かし続けること。

すべての変更がページに現れる必要があるか? ユーザーが気づく可能性のあるものだけだ。内部のリファクタリングを記録するページは読者に流し読みを訓練してしまい、流し読みされるページは、緊急の何かを運ぶ日に失敗する。

この記事の技術的な記述は第三者による確認を受けていません。誤りがあればお知らせください。修正します。

changeloopの関連ページ： changelogの例, 開発者向けドキュメント