owned this note changed 2 months ago
Published Linked with GitHub

如何在技術社群有效發問?

心法:替大家填補資訊的漏洞

我想在這個小節的最開頭補充一點資訊。我認為這是有效提問的「心法」。我在社群或線上會議中經常看到提問者激動地開口就說:「我遇到的問題是,我接了一個馬達,但是它無法運作」、「我接了一個雨滴感測器,它看起來能夠運作,但是…」。

但事實上,這些話語都充滿了資訊漏洞,最明顯的是它們都沒有說明:「整體來說,你到底要做什麼?」許多人會急著進入問題的案發現場,但卻忘記了說明整件事情的背景資訊。你應該先交代的是 – 整體來說,你要做的是什麼?

我想製作一個感測器,當下雨時會自動收衣服。

這是個好的開始。如果再把製作這個裝置所使用的元件加入描述中呢?

我想要用一個雨滴感測器來偵測有沒有下雨,然後根據感測的結果控制伺服馬達來推動一個機構,以實現收衣服的動作。

這樣是不是好多了呢?還能再更好嗎?

我想要用一個雨滴感測器(附上購買連結)來偵測有沒有下雨,然後根據感測的結果控制伺服馬達(型號 SG90)來推動一個機構(目前尚未設計),以實現收衣服的動作。

提到具體的型號和連結通常會讓大家更容易理解你的想法,並且能找到對應的程式碼來測試。

andrew 觀察心得:在專案開發時,許多人都會急著把所有裝置都一次接上 Arduino,然後開始在網路上搜尋範例程式,把大量的程式碼貼到 Arduino IDE 上,並按下編譯按鈕,然後雙手合十祈求老天爺它能夠正常運作。但實際上,正確的做法是先接上一個裝置,然後寫一段測試程式來檢測它的運作狀況。接上更多裝置後,就應該為每個裝置寫測試程式。隨著你接的裝置越多,你寫的測試程式也會越多。最後,再把所有的測試程式整合起來成為一個大程式,這樣才能確保程式的穩定性。

另一個常見的錯誤是「描述不精確」。什麼叫做不精確呢?通常是用一些模糊的名詞來描述現象,如「能動」、「不能跑」、「有抓到」等。

一個受過工程訓練的人應該使用精確的語言來描述現象。例如,如果你想說「雨滴感測器能夠運作」,可以這樣說:

我把雨滴感測器的 AO 接到 Arduino 的 A1,可以透過 analogRead() 拿到雨滴的變化值。

如果你講不出這樣的話,至少你可以說:

我執行這個網路上的範例程式(附上網址),從輸出結果可以看出,數值隨著雨滴變化而變化。

許多提問者也會說:

我執行了網路上的範例程式,但還是發生錯誤。

是不是可以更精確地說明你所謂的「錯誤」具體是什麼?是程式碼在編譯時就發生錯誤?還是程式可以執行,但結果不符合你的預期?如果是後者,那你的預期是什麼?

你會發現,大多數無法問出好問題的人,通常都是因為他們的問題中還存在太多資訊漏洞。許多人會幻想,社群中的大神會非常厲害,能夠從這樣的描述中自動推斷出整個故事。雖然也有這樣的大神,但他們通常都忙著拯救世界,沒有時間回答像你這樣的問題。所以,在提出問題之前,你應該假裝自己是在給一個初學者描述問題,提供任何能幫助他人快速了解脈絡的資訊。每個人的時間都是寶貴的,如果需要不斷往返地提出問題才能確定問題,通常會在過程中磨掉大家對問題的興趣。因此,為了讓大家能快速理解問題,避免這種情況的發生,你應該在提出問題時盡可能提供所有相關的背景資訊。

1. 不要使用圖片貼程式碼

圖片上傳到臉書後,解析度會下降,如果只是幾行的程式碼還可以,但請使用電腦螢幕截圖的方式 按下 Print Screen 按鍵,然後貼到小畫家存成圖檔。不要使用手機翻拍螢幕的方式。

如果有更好的選擇,你不應該使用圖片呈現程式碼,畢竟你是來問問題的,不是來給大家做視力檢查的。

2. 使用適合的工具張貼程式碼

http://pastebin.com/ 可以讓你貼上程式碼,然後產生一個 link 讓你貼在討論區發問。

建議你使用下列的方式:

  1. 先在 Arduino IDE 上開啟程式碼。如果程式碼是從網路上找到的,也先使用 Arduino IDE 開啟一個空白的草稿碼,然後將程式碼貼上並取代原本的程式碼。

  2. 使用 Auto Format (或是按 Ctrl+T) 將程式碼的縮排格式自動設定好。

相信我,這其實很重要。如果你看到提問者提供了一份「全部向左對齊」的程式碼,你不但不想看,還可能會想打人。

  1. 將縮排好的程式碼全選複製,然後在 http://pastebin.com/ 貼上。

記得點選右上方的 Syntax Highlighting,在底下 Syntax Highlighting: 的下拉選單中選擇 Arduino

Paste Expiration: 表示這個連結多久以後就會失效,2 Weeks 是個不錯的選擇,如果兩週了都沒人理你,大概也不會有人回你了 XD

4.確認無誤後,點 Creat New Paste。Pastebin 會產生如下圖的網頁。把網址列附在你的問題貼文上。

為什麼提供程式碼如此重要?你的程式碼可能需要在真實的 Arduino IDE 上編譯才能看出問題,因此越是讓人方便能取得程式碼,就越容易有人會願意幫你在真實的環境下測試。否則再怎樣熱心的人也只會眼睛看一看就猜個方向給你,到頭來是誰浪費了時間呢?

3. 將發問的重點部分剝離出來

假如你想寫個控制程式,按鍵壓住 2 秒後,會將蒐集到的資料寫入 SD 卡;若按壓持續超過 5 秒則退出。但你在處理按鈕行為時遇到了問題,所以打算在社群中發問。

這時候我會建議你將按鍵處理的部分抽離原本的程式碼。作法是另存成一個獨立的程式碼,並且將 SD 卡讀寫的部分以 Serial.println("write data to SD..."); 替代模擬。

這樣做的原因很好理解,如果有人願意幫你測試程式碼,但光是想到得為了你的 SD 卡存取動作得去找 SD 卡接硬體才能執行,大部分的人就懶了。

你應該將真正需要發問的部份抽離出來,另存一個程式檔,確定可以編譯後才貼文發問。以這個例子來說,因為真正想問的是按鈕控制的問題,這個問題甚至可以直接使用 TinkerCAD 等線上 Arduino IDE 進行模擬器測試,不需要實體的設備。而且就軟體開發的角度來說,開發過程中有這樣的獨立單元測試也是好的。

總而言之,程式碼發問的訣竅是 你越容易讓人測試除錯,就越容易有人願意回答你。

4. 交代所使用的函示庫

透過 Arduino IDE 可以讓你從網路上下載函示庫。你必須交代你所使用的函示庫來源為何?例如你嘗試將溫度顯示在 OLED 模組上卻遭遇了問題,但能驅動 OLED 的函示庫不只有一個來源。

你可以打開 Arduino IDE 的 Manage Libraries 並找到你所使用的函示庫。

假如你使用下圖紅框所示的函示庫,請在問題中提供此資訊。

你可以說「使用 Adafruit Feather OLED by Adafruit」的函示庫。或是將底下 More Info 的真實連結貼到問題描述中。以這個例子來說,More Info 事實上指向一個 github 檔案庫連結: https://github.com/adafruit/Adafruit_FeatherOLED

最好也加上函示庫的版本名稱,例如上圖是 v1.0.5。因為有時候函示庫的來源不只一種,或是版本有相容性的問題。也許有人會告訴你用哪個版本比較好,甚至推薦你用另一個更好用的函示庫。但如果你沒有交代這樣的細節,就永遠也不會得到這樣的資訊。

5. 提供所有的錯誤訊息

對!我說的是「所有的」錯誤訊息。

社群中最多初學者詢問的問題類型,就是編譯錯誤!IDE 會在編譯的過程中一一去編譯所用到的函示庫、做鏈結等等,事實上會做很多事情。建議各位在設定中將編譯相關的詳細資訊全都打開。

當發生錯誤時,其實你真正要提供的是 error: 字樣的上下幾行資訊。若真要貼圖的話,請把視窗拉長一點。每次看到有人把訊息視窗縮得很小,然後說「錯誤訊息如下」看了真的很無言

跟前面講的程式碼一樣,最好的方式還是貼到 http://pastebin.com/ 。有注意到錯誤發生時,訊息視窗的右邊有個 Copy error message 的按鈕嗎?這個方法更簡單,按下去就把整個編譯過程的 log 都複製下來了。

接著貼到 http://pastebin.com/ 產生連結即可。

我更建議這種方式,尤其是新手!因為從編譯的 log 可以看出你到底有沒有引入函示庫,你可能主程式有寫,但是 Arduino IDE 根本就沒引用到你的函示庫。這些訊息不會出現在 error: 但是從編譯的過程可以看出來。所以如果你根本不確定到底有沒有正確地引用函示庫,最好的方式就是 Copy error message 然後全部提供。

6. 接線圖 (如果有需要的話)

如果是簡單的配置,你可以用文字說明。或是如果你程式碼寫得夠好,一般有經驗的人可以看程式碼的腳位宣告就知道你怎麼接線。但如果是個複雜的系統,你可能會需要提供接線圖。

推薦使用

  • Wokwi 是一個線上電子模擬器。 您可以使用它來模擬Arduino、ESP32、STM32和許多其他流行的板、部件和感測器。
  • Fritzing

7. 其他資訊

像是: 使用甚麼板子? UNO、Nano、ESP32etc.

如果有特殊供電方式的話,也需要交代 (尤其是你控制馬達的時候)

8. 範本

這裡提供幾個範本:

編譯錯誤

Hi 各位,我想要做一個 ____ 的功能,但是遇到了編譯錯誤的問題。

我所使用的開發板是 ____。

我在 Arduino IDE 上開發,使用的函示庫有 ____ (v1.0.5)。

主要的程式碼在這: https://pastebin.com/xxxxxxxx

但是編譯時遇到了錯誤訊息: https://pastebin.com/ooxxooxx

執行不如預期

Hi 各位,我想要做一個 ____ 的功能,但是遇到了 ____ 的問題。

我所使用的開發板是 ____。供電的方式是 ____。接線圖如下: (發文貼圖)

我在 Arduino IDE 上開發,使用的函示庫有 ____ (v2.0.5) 和 ____ (v3.0)。

主要的程式碼在這: https://pastebin.com/xxxxxxxx

但是執行時,不如我的預期,當我做 ____ 動作時,COM port 輸出的 log 為: https://pastebin.com/xxxeeexxee

參考資料

線上分享程式碼工具整理

  • Arduino Editor
    • 簡述:這是 Arduino 官方的線上編輯器,同時具有線上分享的功能,如 arduino 的 arduino board manager 和 library manager 都有,適合只用過 arduino IDE 的人使用。
      *網址:https://create.arduino.cc/editor
  • Pastebin
    • 簡述:可以讓你貼上程式碼,然後產生一個 link 讓你貼在討論區發問。
    • 網址:http://pastebin.com/
  • GitHub Gist:
    • 簡述:一進到 Gist 就會看到這個頁面,馬上就可以新增一個 Gist。如果你有持續登入 Github 帳號,就會自動是登入的狀態,如果沒有帳號仍然可以使用。這個就像是一個快速的筆記本,可以馬上輸入程式碼或是一些筆記與文字並分享給別人。這適合有github 帳號的人使用的工具。
    • 網址:https://gist.github.com/

功能與需求搞不清楚,專案改來改去也只是剛好

掌握提問的技巧,減少欠人教訓的提問

Select a repo