幫產品加分的 Changelog 要怎麼寫?

| |

我們在上一篇文章〈嗨產品人,我們可以有一份認真的 Changelog 嗎?〉說到規模不同的組織在處理 changelog 的方式不太一樣,也探究了為什麼大型科技公司愛用「bug fixes and performance improvements」公式的為難之處,不過對新創公司來說,changelog 的價值和威力其實很龐大。接著我繼續分享實務上如何寫 changelog,還有把 changelog 寫好的訣竅。

首先,誰是 changelog 的目標受眾?他們為什麼要看 changelog?這兩個關鍵問題決定了 changelog 的模樣。1 我發現,理想上 changelog 要為不同需求程度的受眾所設計,否則也只是雜訊,尤其身處注意力稀缺的時代,高品質的 changelog 才能幫助開發者和受眾溝通。所以一個產品的 changelog 應該有兩份,發揮「安內攘外」的作用:

  • 對外的 changelog:以客戶價值為中心,寫使用者關心、有興趣的事就好
  • 對內的 changelog:全面完整、具體而微,為開發者量身打造。

除此之外,一份健康的 changelog 也取決於骨骼和肌肉的建構——框架要正,比例要均衡。

怎麼寫出好的 changelog?

資深工程師 Olivier Lacan 因為曾吃過 changelog 的悶虧,他在 podcast 節目中說自己「化悲憤為力量」,2017 年開展 keep a changelog 計畫,他希望透過推廣「changelog 不該只是 git log 大集合」的理念和實踐方式,使得 changelog 在程式碼的世界裡能更受重視。

這項專案已經翻譯成 23 種語言,稱得上是目前軟體圈公認的 changelog 指導原則。以下擷自 keep a changelog:

Changelog 撰寫指南

  • 每個版本都應該有獨立的入口,並註記發佈日期
  • 將不同類型的改動分組收納:新功能、維護、優化或錯誤修復等
  • 版本與章節應「可連結化」
  • 命名應遵守語意化版本(Semantic Versioning)格式

綜合 keep a changelog 的提點和其他開發者的建議,我也整理出其他 changelog 的編輯眉角:

  • 在 changelog 上方使用「Unreleased」區塊記錄即將發佈的更新內容,除了一看就知道未來版本中可能會有哪些改動,發佈新版本時直接將「Unreleased」移到新版本的區塊即可,能提升維護效率。
  • 因重大漏洞或安全性問題被撤下(unpublished)的版本通常不會出現在 changelog,但仍建議以 0.0.5 – 2014-12-13 [YANKED] 這樣的方式記錄,其中 [YANKED] 應該和原因一起清楚標示,方便使用者注意到。
  • 盡可能多提供使用者便於判斷的資訊,像是一些 bug 的重要修復可以註明「建議更新」(Update recommended),有些則非必要或緊迫則可以註明 Update not required。
  • 使用被動語態:例如開發者可能直接從自己的待辦清單複製 “Add color selector” 來 changelog 貼上,但應該是 “Add ed color selector” 才對。
  • 用 Markdown 格式。

不過也要提醒,keep a changelog 提供的是大方向,並非一體適用,需要視產品的屬性和受眾調整內容。而一份不太健康的 Changelog 可能會有以下症狀,包括:

  • 使用 git log:因為充滿像是 merge commits 、亂七八糟的提交訊息、文件更新等,對使用者來說都是無意義的資訊。
  • 忽略 Deprecations:使用者升級版本時應該要能預先知道哪些環節可能會出問題,所以 changelog 應該要點出已棄用/淘汰、移除、不推薦使用或可能導致程式碼失效的重大改動。
  • 易混淆的日期格式:使用 yyyy-mm-dd 以外的格式。
  • 過猶不及:發佈 changelog 的頻率過高,使用者難以區分版本之間的顯著差異。
(Photo by Yancy Min on Unsplash)
(Photo by Yancy Min on Unsplash)

有人會問:GitHub 的 Release notes 不好嗎?Olivier Lacan 認為,雖然能做出類似範本的 changelog,但只能在 GitHub 上瀏覽,不一定所有使用者都會造訪(不過至少是個好的起點,幫助你養成紀錄的習慣);那 git log 呢?他解釋 commit 的目的是記錄程式碼從一個狀態發展到另一個狀態的過程中的最小步驟;changelog 的目的則是記錄這些狀態之間「值得注意的差異之處」,所以就像好的註解(comment)和程式碼之間的區別一樣,changelog 和 commit log 也是如此:一個是描述原因(why),另一個描述方法(how)。2

說了這麼多,不妨參考 Olivier Lacan 的 changelog 範本 實做看看,你可能會逐漸發展出自己的 changelog 風格。但萬變不離其宗的是「溝通」,畢竟 changelog 是寫給人,而不是機器看的呀。我很喜歡開發者 Daniel P. Clark 的形容:3

Changelog 就像用鳥瞰視角觀看地圖,顯示去過哪裡和現在所處的地方。眼前這份 changelog 如果缺了過去發生的變化,就會讓地圖變得有點模糊,迫使開發者只能去「考古」。

changelog 模範生排排站,幾乎就像是系出同門

除了參考 Olivier Lacan 的 changelog 範本changelogs.gallery 這個網站還收錄一些 SaaS 公司或產品的 changelog 模範生,共通點是看得出有定期維護,一目瞭然,包括我們曾介紹過的 LinearReadwise 都入列。

有趣的是,在 GitHub 擔任 Staff product desiner 的 Brian Lovin 碰巧發現近幾年 changelog 頁面的風格似乎走向同質化,不禁開玩笑說現在 changelog 都要長得跟 SaaS 新創 Linear、Vecel、Raycast 和 Framer 的 changelog 一樣,這番觀察在 Twitter 也引起迴響。這或許這某程度上反映了軟體圈的共識,同時讓新進的創業者和開發者能照著「模板」打安全牌。(延伸閱讀:滲透各大網站,插畫風格「Corporate Memphis」描繪出科技烏托邦幻象

除了中規中矩的 changelog,寫到這裡我想到去年 Slack 的一波操作,讓我特別印象深刻。

在疫情攪弄的崩潰氛圍中,寫給使用者的溫暖文字格外觸動人心,算是利用 changelog 為品牌行銷(或其實是公關小心機?)的另類手法,看起來成效也還是不錯的。

新創團隊怎麼寫 changelog ?

Linear 共同創辦人 Jori Lallo 說他們 2019 年 4 月就開始有意識的投入 changelog4,一年內發佈了 50 多條 changelog。CEO 暨共同創辦人 Karri Saarinen 曾擔任 Airbnb 首席設計師,Coinbase 的設計也出自他手,他發現經營 changelog 比想像中帶來更多好處,呼籲新創公司都應該好好寫 changelog。他萃取自家經驗提供了幾項執行建議:

  • 制訂排程,例如每週或每兩週一次發佈,對齊開發週期(sprint),等於是發表階段性成果。(像是台灣聲音創作平台Firstory 從 2020 年開始每兩週在 Notion 發表 changelog。)
  • 團隊成員輪流撰寫,但通常功能的主要負責人也都要寫。
  • 以一至三個較大的變更為主軸,把瑣碎的小 bug 集中在同一類,但也要讓使用者感受到你有注意到一些雖小卻擾人的 bug。
  • 視情況附上這項變更的截圖或影片,方便使用者快速理解上手。
  • 在使用者 onboarding 的流程裡加入訂閱更新通知的環節。

幫你寫好 changelog 也是一門生意

維護 changelog 確實需要投入心力和人力,礙於各式各樣的提交訊息和檔案名稱,要能完全自動生成仍有技術門檻存在,不過近年也陸續有人看準寫 changelog 的痛點,或是整合用戶管理的需求打造一站式服務,推出為開發者減輕摩擦力的工具。

(Photo by Cherrydeck on Unsplash)
(Photo by Cherrydeck on Unsplash)

跨平台整合專案管理工具、自動化發佈 changelog

  • DoubleLoop:整合 Linear、Github、Slack、Jira、Shortcut、Zapier 和 GA 等服務,自動生成對內部的 changelog,也能選取更新項目,進一步編輯為適合對外部使用者傳達的故事,並結合對產品指標的追蹤,掌握優化方向。目前還在 beta 階段所以免費。
  • Makelog :力推快速生成美觀的 changelog 頁面,一樣能整合 Github、Slack、Jira、Shortcut 等等並自動化發佈。目前免費。

善用 changelog 蒐集使用者回饋、提高轉換率和回訪率

  • Beamer:可嵌入多種樣式的 in-app widget(小工具),使用者造訪服務時可以對 changelog 按下不同 emoji,回饋的門檻變低之外,開發者也可透過分析服務掌握使用者對更新的好感度。除了 widget,也可以選擇為 changlog 製作 SEO 優化的獨立頁面,可客製化域名和風格。費用依據產品團隊的規模不同,從免費到每月 49、99 或 249 美元。
  • Olvy:和 Beamer 的功能差不多,不過費用相對親民,有免費或每月 24 美元兩種方案,並提供 60 天免費試用。
  • Onset:功能相對單純,沒有數據分析服務。有免費、每月 30 或 60 美元三種方案。
  • Headway:類似 Onset,有免費或每月 29 美元兩種方案。
  • AnnounceKit:創辦人當初要找一個可以發佈產品更新的服務,發現 Headway 的時候覺得不錯也不難,應該可以在一兩個月內自己打造出來,會是一個很好的 side project。殊不知想像太美好——他們最後花了超過半年才推出 AnnounceKit。比較特別的是提供「細分使用者」的功能,根據使用者的不同屬性,把更新說明發送給相關的使用者,而非廣發。收費方案和 Beamer 一樣,每月 49、99 或 249 美元。

在我看來,changelog 並不是寫完發佈抵達的終點,而是與使用者建立連結的起點、開啟一場累積信任值的馬拉松,至死方休。軟體雖然吞噬了世界,但我作為使用者仍然貪心的期盼,那份寄託於 changelog 的人味終究不會被吞噬殆盡。

資料來源:

  1. A Beginner’s Guide to Git — What is a Changelog and How to Generate it
  2. Keep a CHANGELOG with Olivier Lacan (The Changelog #127)

(文章代表圖:截自 Pitch

本文依 CC 創用姓名標示 - 非商業性 - 相同方式分享 4.0 國際釋出
Previous

科技創業週報 #322:我怎麼用子彈筆記管理待辦事項

星箭廣播 146 集––「我們聽什麼?」特輯 3:六檔科技 Podcast 推薦!

Next

發佈留言

Share via
Copy link
Powered by Social Snap