一日一技:如何阅读技术文档(直播文案)

语言: CN / TW / HK

摄影:产品经理 

一盘这个酱蟹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

未闻 Code·知识星球开放啦!

一对一答疑爬虫相关问题

职业生涯咨询

面试经验分享

每周直播分享

......

未闻 Code·知识星球期待与你相见~

一二线大厂在职员工

十多年码龄的编程老鸟

国内外高校在读学生

中小学刚刚入门的新人

“未闻 Code技术交流群” 等你来!

入群方式:添加微信“mekingname”,备注“粉丝群”(谢绝广告党,非诚勿扰!)