如何寫出絕佳的發行說明

圖像來源： opensource.com

恭喜你！你已經準備發布你的軟體包的最新版本了。現在，你需要保證你的發行說明整潔有序。當然，你可以寫上一句「bug 修復以及性能改進」然後就算完成，但這並不能給你的用戶傳達任何信息。

發行說明同時用於支持和營銷。它可以告訴你的的用戶，為什麼這個發布版本對他們很重要，並可以向潛在用戶展示你的軟體。所以，你會希望它的內容簡潔、易懂，最重要的是：目的明確。寫發行說明的方式不止一種，所以本文只是一般提議，並不是一個強制要求。

現在一個流行的趨勢，是將發行說明寫成包含一堆蠢事的敘事文。如果你想這麼寫，那請自便 —— 不過要記住，笑話通常是上下文相關的，你覺得很滑稽的內容，可能在你的讀者眼裡會變得索然無味。而且，不要忘了將那些重要信息寫進來。

入門

你能從本文里學到的最主要的經驗，可能就是這一條：你的發行說明要寫給讀它的人看。對於面向用戶的軟體，發行說明中要注重面向用戶的行為，而不是軟體的內部實現。舉個例子：寫「點擊『取消』按鈕會把你的電腦點著」，而不要寫「在 cancelThatThing 函數中，thermalEventTrigger 的默認值被設為 True」。

嘗試將每一條說明限制在一到兩句話。重點在於突出強調重要部分，而不是給出詳盡的解釋。如果你有一個公開的問題追蹤頁面，你可以在說明中包含問題鏈接（或者問題編號），這樣關注此問題的讀者可以通過鏈接來查看問題的詳細內容。

你並不需要嚴格按照這種方法來寫發行說明，但我比較喜歡下面的格式。開頭寫上版本號，以及發布日期。對於主要版本，你可能要再寫幾句話，來突出本次發布的主題。比如，「本次發布的重點在於添加了郵件客戶端，因為這是所有軟體的最終結束狀態。」

兼容性更改

如果新版本中包含兼容性或默認行為的變更，你最好將它們著重寫出。你的用戶、以及提供用戶支持的人會感謝你的。在發行說明中描述會遇到行為變更的場景，如何處理變更，以及如果用戶對變更不採取行動會導致的後果。對於某些次要版本，你可能沒有任何會導致不兼容的變更，那你可以省略此部分。

功能及改進

現在，你該炫耀你的軟體包含的那些酷的、新奇的東西了，但是要記得站在用戶的角度來寫。比如，「該軟體現在支持自動發現午餐照片，並將其發布到 Instagram 上。」

已解決的問題

沒有軟體是完美的，所以在這部分中你需要告訴讀者，你的團隊為了使這個項目更好一點而做的所有努力工作。因為那些不好的行為已經被解決了，所以應該用過去式來寫這一部分。如果某個 bug 的產生原因很明確，寫上相關信息。一些項目還在文檔此節中包含修復的 bug。

已知問題

因為沒有軟體是完美的，所以永遠會存在未解決的 bug。在這一節中，你需要列出這些已知的問題。你不需要列出所有的問題；主要是影響功能的錯誤，尤其是那些在上個版本發布後發現的 bug。這一部分的文字用將來時態寫出。當你把這些問題解決，你只需要改變動詞的時態，然後把它們移到上個部分即可。

作者簡介：

Ben Cotten - Ben Cotten 是一個受過專業訓練的氣象學家，但他現在是一位高性能計算工程師。Ben 是一位循環計算領域的佈道者。他是 Fedora 的用戶及貢獻者，與他人一同創辦了一個本地開源會議組，是開源計劃的成員，還是軟體自由保護的支持者。你可以在 Twitter 上找到他（@FunnelFiasco）。

譯者簡介：

StdioA —— Pythoner, Player.

via: https://opensource.com/article/17/3/how-to-improve-release-notes

作者：Ben Cotton 譯者：StdioA 校對：jasminepeng

本文由 LCTT 原創編譯，Linux中國 榮譽推出

本文轉載來自 Linux 中國: https://github.com/Linux-CN/archive