開發者與官方文件之間總有一種尷尬的距離感
「看不懂文件是因為自己實力不夠嗎？」 我曾經長時間相信這句話。
1. “好像只有我不懂”
框架、函式庫、REST API、雲端服務…… 現在大多數都擁有完善的官方文件。 問題是……我還是無法真正理解它們。
剛開始時，我是這樣想的。
“啊…還是因為實力不足吧。 多學習一點，總有一天這份文件也能順利閱讀…”
於是我努力閱讀。結果卻是：
- 原理不清楚
- 何為概念、何為實際使用範例混淆不清
- 明明讀過內容，卻在寫程式時手不聽話
- 文件量為什麼這麼大？
現在我已經不再把自己稱作「初學者」了。 但每當看到新的函式庫文件，心裡仍會有這樣的聲音。
“哇…又要開始學習了…”
我已經知道，這不僅僅是實力不足。
2. 文件通常是「創作者視角」寫成的
文件難懂的最大原因，似乎是大多數官方文件是以「創作者的腦中結構」為基礎寫成的。
- 他們已經
- 知道內部結構
- 知道為什麼會這樣設計
- 知道有哪些限制
- 知道這個函式在哪裡、如何被呼叫
- 因此文件中往往會寫到
- 這個方法接受這些參數
- 這個類型會被回傳
- 在這種情況下會拋出例外
- 用這個可以做什麼…
問題是，我們不是那個創造程式的人。
我們關心的通常是這些問題。
- “我應該從哪裡開始？”
- “我現在遇到的這個問題，應該看文件的哪一部分？”
- “這個選項實際上在什麼情況下需要？”
- “這行程式碼實際上什麼時候被呼叫？”
但文件卻這樣說。
“這個選項使用 foo 動作和 bar 策略來執行 baz。”
…到這裡就想先跑個範例了。
3. “我的文件最終對別人也很難懂”
有趣的是，我也會為自己寫的 API 或函式庫寫文件。 那時同樣會以「創作者視角」寫。
- “這個函式做這個功能…”
- “這個端點接受這些參數…”
- “這個 JSON 會回傳這種結構…”
- “成功/失敗時回應是這樣…”
然後我會想。
“這樣應該已經相當友善的文件了吧？”
但同事的反應大多是這樣。
- “能不能先口頭說一次？”
- “文件雖然有，但…直接問比較快。”
更有趣的是，我也會在以前寫的文件中找不到自己。
多年以前寫的 API，想再用時打開舊文件：
“咦…這是我寫的嗎？ 為什麼這樣說得怪怪的…？”
那時我明白了。
- 寫文件並不等於「易於理解」。
- 我對官方文件抱怨的資格…其實不多。😅
4. 官方文件本來「剛開始不易懂」是正常的
每個專案都會使用至少一個函式庫或套件。 這些文件往往被固定在瀏覽器標籤，工作時不斷打開。
奇怪的是。
- 第一次閱讀時，會想「到底在說什麼…」
- 專案結束時再次閱讀，卻能「明白了」
經常會這樣想。
“不，原來這裡寫的是這樣？ 我以前確實看過，但當時不懂它的意思…”
為什麼會這樣？
- 要理解文件內容，需要
- 一定程度的實作經驗與上下文
- 而要累積這些經驗，
- 必須先大致閱讀文件，並嘗試做些東西
也就是說，理解文件需要先理解文件，形成一個奇怪的循環。
所以我現在這樣想。
“官方文件不是一次就能理解的。 需要在多個專案中反覆閱讀，才能真正看懂。”
因此，剛開始不懂是正常的。 不是因為你不夠好，而是因為它本身的結構。
5. 非英語國家開發者的難度 +2
此外，我們還有「非英語國家開發者」這個障礙。
- 英文句子本身可以閱讀
- 技術術語也相當熟悉
- 喜歡閱讀書籍、文章，感覺「閱讀理解」不差
但閱讀官方文件時，腦子會更快感到疲憊。
這不是實力不足，而是：
- 英語本身需要持續的「認知成本」
- 再加上
- 新概念
- 生疏的 API 設計
- 抽象的範例程式碼 同時湧入
也就是說，你在同樣的內容上比別人消耗更多能量。 自然會更疲憊、更難以理解。
所以當你想「為什麼我閱讀官方文件這麼吃力？」時，告訴自己：
“我已經在帶著障礙努力前進。”
6. 但我們還有幾個生存技巧
不只是安慰，以下是我在寫作過程中學到的「文件生存技巧」。
6-1. 放棄「從頭到尾閱讀」的慾望
- 官方文件通常像「參考手冊 + 字典」的感覺。
- 不是像入門書那樣「從第一頁到最後一頁都能理解」。
所以我會：
- 先粗略瀏覽「Getting Started / Quickstart / Tutorial」
- 其餘部分則視為
- 搜尋用
- 遇到問題時翻閱
6-2. 先用範例理解，再閱讀說明
- 寫一行程式碼
- 故意觸發一次錯誤
- 搜尋錯誤訊息，然後回去看文件
這樣，文件的句子會變得更易懂。
- 第一次閱讀：
“我不明白這句話…”
- 反覆嘗試後再次閱讀：
“啊，這就是我遇到的那個錯誤說明。”
失敗經驗之後，文件就像故事一樣流暢。
6-3. 用自己的語言做筆記
官方文件必須用「他們的語言」寫成。 我會經常做這樣的筆記。
- “這個選項設為 true，實際上就是
XXX 模式” - “這個函式就像『X 產生工廠』”
- “這段一定要背起來。深入理解留到之後…”
之後我再看「自己的文件」時，官方文件和筆記一起，會更有把握。 （當然，有時筆記也會變成「這是什麼？」）
7. 你並不是因為自己不夠好
如果你已經讀到這裡，可能你也曾在官方文件前嘆息。
- 多次閱讀仍不懂的句子
- 昨天看過但今天還得再找的章節
- 只有在解決問題後才明白的句子
每次遇到這種情況，請記住：
- 你不是唯一的。
- 現在表現優秀的開發者也常常迷失。
- 甚至每天使用該函式庫的人，往往比官方文件更常搜尋 Stack Overflow 或 GitHub Issue。
官方文件本來就寫得難懂，這不是你的錯。
我們只需要：
- 再讀一次
- 如果還不懂，先寫程式
- 失敗後再翻閱文件
- 直到有一天
“啊，原來這句話是這樣寫的…”
這就是「作為開發者的生活」的一部分。
所以，對於今天仍在文件前失落的人，我想說：
“你並沒有錯。 你只是在正常的開發節奏中前進。”
我們仍在文件前茫然，打開數十個標籤，尋找昨天的頁面，卻仍在前進。專案還是會繼續，程式碼也會不斷增長。🙂
目前沒有評論。