由於本篇篇幅比預計的長，寫作時間也超過預期，為了能夠保持寫三十天文章的耐力，決定將篇幅超過一定長度的主題拆分，讓自己能夠針對主題做比較好的解說，而不是帶大家走馬看花。

前言

今天來講講如何敘述一個議題（issue），通常議題有分兩種，一種是功能請求（feature request），另一種是異常回報（bug report）[^1][^2]。由於功能請求中關於需求的描述會涉及不少知識與經驗，使用者和工程師的相關描述可能又大不相同，這方面的知識很難一次論述完整；而異常回報的描述則較為通泛，主要是講述在回報異常時，應該要附上哪些資訊會對開發者更有幫助，不太區分角色，較為簡單。所以本篇先著重在怎樣描述異常。

情境

「為什麼我們要學會如何描述一個（異常）問題呢？問題描述有什麼難的？不就是把遇到的問題講出來就好了嗎？難道我講的還不夠清楚嗎？」我想這是多數使用者甚至少數開發者聽到這個主題會有的疑惑，事實上這是很正常的反應，對於多數異常回報者來說，他們已經盡力地把遇到的異常描述出來了，他們眼中的異常就是這樣，對於協助我們指出異常的使用者，我們很難用比較強硬的態度說：「這些資訊太少了，我不接受」。到最後我們也只能抱著疑惑的心情嘗試找出使用者遇到的異常，但在資訊不足的情況下，這些異常通常都石沈大海。尷尬的是，你若把異常議題關掉、結案，使用者可能還會抗議，於是這些議題就成為議題追蹤工具的萬年大石頭，卡在那邊不上不下。

崩潰的是，在議題追蹤工具裡不只前述的項目卡在那裡，甚至有更多的陳年議題是前輩們留下來的。裡面只簡短地用兩三句話（甚至更短）描述遇到什麼問題，再沒有其他資訊。我們看不懂這個問題到底在說什麼，我們也不知道這個問題要怎麼重現，我們更不知道這個問題是哪個版本的事，是不是在現在的版本已經不會出現了？抱著疑惑、抱著頭，我們・真的・非常・苦惱。 _(:3」∠)＿

目的

在回報問題時提供充足的資訊，能夠讓開發者更快解決。

是的，當我們在回報問題時提供充足的資訊，會讓開發者更能精準判斷這個「症狀」的「病因」是什麼，才能更精準的解決軟體的病灶[^3]，從而快速解決問題，既省下開發者的時間成本，使用者也能更快的享受問題排除的成果。

所以學會如何描述問題是任何與這份程式有關聯的人都應該要知道的。使用者要知道、客服要知道、專案經理要知道、工程師更要知道。如此一來，使用者或客戶能夠明確將情況描述給開發團隊，讓這異常迅速排除，繼續愉快的使用產品。若是使用者沒有這份知識時，客服就要幫忙過濾，在與使用者的溝通中引導他們把這些資訊回答出來，避免讓不必要的雜訊干擾開發團隊的進度。專案經理更要嚴格把關將送進開發團隊的異常回報，要求客服把缺漏的資訊補上，讓開發團隊可以將時間專注在解決異常而不是重新尋找如何重現它。工程師則更應該要謹記，現在的詳細記錄異常資訊，可以讓我們都不再多背一袋技術債，絕對不要嫌麻煩而省略，不然未來將會耗費更多時間重新釐清這個異常。

作法

那在回報異常前，我們應注意哪些事項呢？那就是查看當前的議題清單裡，有沒有和我們所遇到的異常相同的情況，避免重複（duplicate）回報。同樣的異常應該集中在同個議題討論，而不是散落在清單各處，這樣只會增加開發團隊的排除成本。當我們發現已經有既定異常議題存在時，可以先嘗試了解該討論串的內容，若仍然無法排除，則可以將原本要回報的內容，於該議題討論串中回覆，增加樣本數。

那麼有哪些資訊是在回報異常時需要附上的呢？這邊先以清單的方式表述：

• 標題（Issue title）
• 版本（Version number）
• 問題簡述（Describe the problem）
• 重現步驟（Steps to reproduce）
• 預期行為（ What I expected）
• 實際行為（What happened instead）
• 影像（Screenshot / Video）
• 環境（Environments）
• 脈絡或程式碼（Context / Source）
• 備註（Additional details）

讀者們可以先想想看為什麼會需要這些資訊，詳細的解說會在明天的文章中繼續向各位闡述。並且提到遇到不合作的情況下怎樣處理比較好，還有什麼方式可以讓回報者比較願意回報完整的訊息，敬請期待囉。

TO BE CONTINUED

---

本日感想（無關主題）
原本是想一口氣把這個主題講述完整再休息的，但看了計時器以目前的字數統計，驚覺如果要每天產出這樣完整的文章，要嘛就是耽誤原有工作，要嘛就是幾乎不用睡，無論哪項都會導致敝人在鐵人三十中不得不中斷，我想這就本末導致了。

之後比較文章可能都會至少分成上下兩篇，上篇帶讀者了解這個主題的情境、目的，並稍微提到作法的概要，在於下篇將作法完整的表述，也能讓讀者可以先思考看看。

最後，感謝各位讀者的體諒，我們明天見！ = D

[^1]：除了此兩種外，還有一種類型容易被當作議題，但事實上是不建議提交在議題追蹤工具，那就是使用上的疑惑（usage question），這類型的議題通常建議先讀相關文件、使用者手冊、觀看影片教學、在論壇、社群、通訊平台上發問。如果是商業產品，則應該由客服處理，而不是丟給研發工程師。
[^2]：關於 bug 這個詞，比較口語的部分我會使用「問題」作為對應，而在比較書面的部分我會使用「異常」作為代表。畢竟「問題」這個詞太過廣義，有可能是指 bug，也有可能是指 question，而「異常」則嚴謹的多。當然，平時在聊天時，大家還是繼續說 bug 唄。
[^3]：通常「症」指的是疾病的徵象，「病」才是問題起源。