一日一技：如何阅读技术文档（直播文案）

今天这篇文章，是我今天（1月16日）知识星球直播的概要。详细内容，大家可以观看直播回放视频。已经在知识星球的同学，直接点击连接就能查看回放。尚未加入星球的同学，请在一周后，到我的B站上观看视频。

我平常在公众号粉丝群里面常说，要多看官方文档，少看博客。有些同学就说，官方文档看不懂啊。例如你想学习Python的logging模块，然后你会看到logging — Python 的日志记录工具 — Python 3.10.2 文档是下面这样的：

又比如你想学习Golang里面net/http的使用，你会看到它的文档http package - net/http - pkg.go.dev是这样的：

这样的文档，你看完以后，可能也写不出一个完整的可以运行的程序。但还有另一种文档，你就算第一次接触这个软件或者框架，你也能跟着它的指导写代码，例如Scrapy的官方教程Scrapy Tutorial — Scrapy 2.5.1 documentation。你甚至不会英语也没关系，你就跟着黄绿背景的框框写命令，复制代码，你也可以把爬虫搞出来。

为什么会有这样的差异呢？因为我们平常笼统地叫做文档的东西，其实有两种。前两个反例是API Reference，API接口文档。Scrapy的叫做教程。API接口文档和教程文档是面向两种不同用途的。

Python的Logging模块也有教程文档版：Logging HOWTO。

教程文档其实没有什么好说的，就是一步一步跟着走就能完成。教程文档会告诉你，你不知道你不知道的东西。

而API接口文档看起来就会比较费劲，因为它是用来告诉你你知道你不知道的东西。例如你知道有某个功能某个函数，但是你不知道它的具体语法怎么写，这个时候就用API接口文档。

在直播里面，我以Scrapy下载器中间件和Pyppeteer为例来进行说明。我知道下载器中间件怎么激活，我也知道我要修改代理IP，应该编写下载器中间件的process_request方法，但是这个方法接受哪些参数？它能返回什么东西？这个时候我就可以到API接口文档里面进行查询。

同理，在Pyppeteer的Github仓库里面，Readme写了两个简单的例子告诉我怎么使用它打开一个网页。但是我应该怎么使用XPath从页面上选中一个元素，然后点击它？这个时候就可以到API接口文档里面，搜索xpath，找到对应的方法，看它接受什么参数，返回什么内容，会报什么错。

直播的最后，我和大家一起试图从net/http的API文档里面寻找怎么更换代理IP。由于我用Go发起网络请求，主要是使用imroc/req，很少使用net/http，我处于我不知道我不知道的状态，于是我跟大家一起崩溃在了这个API接口文档里面。