深藏若虛

如何敘述異常回報

How to describe a bug report

本文是今年在 IThome 鐵人賽所寫的文章,好像也是唯一有完整釋出的文章(艸),用心寫完這篇就好既無力了 XD。在這邊稍微把這篇原本分四天的文章進行整併、校閱,讓有興趣閱讀的人可以讀得比較舒適。

前言

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

情境

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

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

Read on →

Collection

Games

General

Information Technology

Traditional Medecine