# 用新技術前請先閱讀官方文檔

- 作者：林鼎淵（Dean Lin）
- 網址：https://deanlin.net/blog/202205/read-the-official-docs-first/
- 發布：2022-05-23
- 主題：職涯成長
- 標籤：Documentation、Official Document、Life Lessons、生活案例、Framework
- 摘要：有時我們覺得某個框架、套件很難用，常常寫到一半就卡住；除了可能是它本身設計的問題外，很多時候是因為沒仔細看官方文檔，導致我們拋棄好用的現成方案，選擇了一條孤獨難走的道路。

有時我們覺得某個框架、套件很難用，常常寫到一半就卡住；除了可能是它本身設計的問題外，很多時候是因為沒仔細看官方文檔，導致我們拋棄好用的現成方案，選擇了一條孤獨難走的道路。

```
大綱
ㄧ、別談技術，先來看看筆者發生的蠢事
二、也許不是關關難過，而是從沒看過
三、如果方向是錯的，那離目標會越來越遠
四、總結

```

## ㄧ、別談技術，先來看看筆者發生的蠢事

筆者過去購買家電時有個壞習慣，就是幾乎不看說明書；總覺得憑藉自己的理工頭腦可以輕鬆駕馭這些產品。

儘管大多數的狀況下我都能無師自通，但現實生活總是會找機會賞你幾個巴掌，有時我沾沾自喜的用法，過一段時間才發現根本是錯誤的。

就拿吸塵器來舉例好了，現代的吸塵器往往是多功能的，吸地、吸床單、吸鍵盤各有不同的吸頭；自以為聰明的我，認為吸附面積最大的頭一定是拿來吸地板的，但用了一陣子後總覺得馬力不夠，地板上常常有灰塵很難吸起來。

此時我去看說明書才明白，原來我一直拿吸床單的頭來吸地板！？儘管這樣也能使用，但卻無法發揮出每個吸頭應有的功效。

> `會發生這個蠢事，就是因為我覺得這個東西很簡單，沒必要看說明書。`

## 二、也許不是關關難過，而是從沒看過

現在的技術日新月異，很多時候開發人員真的沒時間慢慢看文檔。

如果今天的需求較為簡單，那可能用套件的範例程式就能解決；但萬一需求較為複雜，那勢必要更深入的研究套件。

理論上是這麼說，但實際上有不少工程師，是選擇投入大量精力在魔改基礎的範例程式，而非去深入閱讀官方文檔。

就拿前端（Vue.js）來舉例，框架提供的 Component 有很多的 Props 可以使用；但很多人會選擇自己用 watch、computed 刻出一樣的功能。

一個問題往往有多種解決方案，但站在筆者的角度，除非框架沒有提供 Solution，不然盡量不要自己手刻，這些多餘的程式碼會導致日後的維護更加困難。

> `遇到需求請先閱讀官方文檔，很多時候有更省力的解決方案。`

## 三、如果方向是錯的，那離目標會越來越遠

> 如果你人在台中，接下來打算前往台南；但車子卻一直往北開，你認為什麼時候才會抵達目的地？

前兩個案例，我們只是在解決問題的路上多花一點力氣；但在這個案例，是整個團隊白費力氣。

幾年前筆者曾選擇 Adonis.js 這個 Node.js 的框架來開發後端，前期開發的很順利，但隨著專案結構越來越複雜，我們發現這個框架缺少許多實用的功能，甚至還遇到不少需要等待作者維修的 Bug。

儘管當時已經使用它開發了 3 個月，但最終開發團隊還是決定忍痛放棄，跳槽到其他穩定的框架；而這次的失誤，導致系統架構要重新設計，不少程式需要重新撰寫。

> `會發生這個慘劇，是因為貿然選擇了一個不夠成熟的框架，且事前評估不足就直接投入開發。`

## 四、總結

古人是因為缺少前人的經驗，才需要靠自己試錯來尋找答案。

現在資訊這麼發達，大部分的坑都有前輩幫你踩過了，沒必要親自去體驗。

儘管讀文檔要花費不少時間，但在很多時候它可以幫你解省更多時間。

> 磨刀不誤砍柴工，古人的話別當耳邊風。

---

關於作者：林鼎淵（Dean Lin），台灣的生成式 AI 企業內訓講師、外商資安公司軟體專家，也是生成式 AI 創新學院發起人。出版 7 本書（包含全台第一本 ChatGPT 應用專書），兩度獲得 iThome 鐵人賽佳作，累積上百場授課與顧問經驗。（https://deanlin.net/about/）
引用時請附上原文網址：https://deanlin.net/blog/202205/read-the-official-docs-first/