一日一技：如何閱讀技術文件（直播文案）

攝影：產品經理 

一盤這個醬蟹200多

今天這篇文章，是我今天（1月16日）知識星球直播的概要。詳細內容，大家可以觀看直播回放影片。已經在知識星球的同學，直接點選連線就能查看回放。尚未加入星球的同學，請在一週後，到我的B站上觀看影片。

我平常在公眾號粉絲群裡面常說，要多看官方文件，少看部落格。有些同學就說，官方文件看不懂啊。例如你想學習Python的logging模組，然後你會看到 logging — Python 的日誌記錄工具 — Python 3.10.2 文件 [1] 是下面這樣的：

又比如你想學習Golang裡面 net/http 的使用，你會看到它的文件 http package - net/http - pkg.go.dev [2] 是這樣的：

這樣的文件，你看完以後，可能也寫不出一個完整的可以執行的程式。但還有另一種文件，你就算第一次接觸這個軟體或者框架，你也能跟著它的指導寫程式碼，例如Scrapy的官方教程 Scrapy Tutorial — Scrapy 2.5.1 documentation [3] 。你甚至不會英語也沒關係，你就跟著黃綠背景的框框寫命令，複製程式碼，你也可以把爬蟲搞出來。

為什麼會有這樣的差異呢？因為我們平常籠統地叫做 文件 的東西，其實有兩種。前兩個反例是 API Reference ，API介面文件。Scrapy的叫做 Tutorial 教程 。API介面文件和教程文件是面向兩種不同用途的。

Python的Logging模組也有教程文件版： Logging HOWTO [4] 。

教程文件其實沒有什麼好說的，就是一步一步跟著走就能完成。教程文件會告訴你， 你不知道你不知道 的東西。

而API介面文件看起來就會比較費勁，因為它是用來告訴你 你知道你不知道 的東西。例如你知道有某個功能某個函式，但是你不知道它的具體語法怎麼寫，這個時候就用API介面文件。

在直播裡面，我以Scrapy下載器中介軟體和Pyppeteer為例來進行說明。我知道下載器中介軟體怎麼啟用，我也知道我要修改代理IP，應該編寫下載器中介軟體的 process_request 方法，但是這個方法接受哪些引數？它能返回什麼東西？這個時候我就可以到API介面文件裡面進行查詢。

同理，在Pyppeteer的Github倉庫裡面，Readme寫了兩個簡單的例子告訴我怎麼使用它開啟一個網頁。但是我應該怎麼使用XPath從頁面上選中一個元素，然後點選它？這個時候就可以到API介面文件裡面，搜尋 xpath ，找到對應的方法，看它接受什麼引數，返回什麼內容，會報什麼錯。

直播的最後，我和大家一起試圖從 net/http 的API文件裡面尋找怎麼更換代理IP。由於我用Go發起網路請求，主要是使用 imroc/req ，很少使用 net/http ，我處於 我不知道我不知道 的狀態，於是我跟大家一起崩潰在了這個API介面文件裡面。

參考文獻

[1] logging — Python 的日誌記錄工具 — Python 3.10.2 文件:  https://docs.python.org/zh-cn/3/library/logging.html

[2] http package - net/http - pkg.go.dev:  https://pkg.go.dev/net/http

[3] Scrapy Tutorial — Scrapy 2.5.1 documentation:  https://docs.scrapy.org/en/latest/intro/tutorial.html

[4] Logging HOWTO:  https://docs.python.org/3/howto/logging.html#logging-howto