如何阅读技术文档

“大神你好,请问我打算学习Django,应该怎么做?” 答:“去看文档” “Django的文档都是英文,我看不下去,怎么办” 答:“bla bla bla…. 关于英文的重要性” “Django的文档那么多,我是不是都得看完才行?” 答:“不用,用到哪看到哪,没事可以随意浏览”

上面的对话经常会出现在我的QQ消息框中,有很多初学Django的人通常都会有这样或者那样的疑问,我之前写过一篇 《从Django的Turotial中可以学到什么》 ,在那篇文章中我总结过,练习完这个新手入门教程,基本上可以独自开发web项目了。但是剩下的其他文档怎么办?不用看了吗?怎么个看法,据说一千多页呢!

这篇文章我根据我的想法讨论下应该如何阅读Django的文档比较合适。

先来分享下我的经历

在我刚从Java转到Python时就直接接触的Django框架,当时同事给我推荐过一本Django的英文书《Practical Django Projects》,当时看了几页,因为速度太慢,就转向这个网站:http://djangobook.py3k.cn/2.0/ 。 当时我们使用的Django是1.3的版本,这个翻译的网站翻译的文档版本是1.1,但大部分差不多,也算是个能快速了解Django的途径。

后来随着对Django使用的越来越多,发现翻译的东西虽然能让你快速了解Django的一些东西,但是很多细节的地方还是需要去看英文文档才能明白,究其原因主要有两个:一是文档更新慢,二是文档是有志愿者参与翻译的,水平不一,细致程度也不一。于是就很少再去看这个中文的了。

再之后,每每遇到问题请教同事或者在网上查得时候总能得到这样的反馈——你看过这部分的文档吗?!先去看看文档再来讨论。于是乎,在这样不断的被鄙视过程中不断的熟悉了Django的官方文档,对于Django的问题也终于有了正确的认识——那就是,有问题就去看文档;出错了,一定是你文档看的不仔细。

除了在这样被鄙视的的状态下去看文档的,自己也尝试过去挨篇读文档,唯一的收获就是大概知道有哪些东西了,附带的收获就是对文档这东西不那么陌生了。

再后来基本上就是用到一个模块,遇到问题,就去自己阅读相应的文档。当时还翻译了三部分: Django1.4数据库访问优化部分 这个是项目运行时遇到问题之后去仔细看了下,然后给同事做了分享,花了点时间翻译了下。另一部分是: Django1.4文档的class-based-views这是为了学习怎么使用Class Based View才开始翻译的,这算是我自己集中精力的一种方式,当你的大脑是在无法接受这些英文字母时,一句一句的去翻译会让你打起精神来。还有一部分middleware的翻译,也是基于同样的目的。

翻译几篇之后基本上就对Django的文档中的常用语比较熟悉了,剩下的就是花点时间去看看,或者用到了就去看看。

这就是大概的经历,下面稍稍总结下。

战略上藐视它

在一开始学习Django的时候,第一次打开官网,肯定会被如此多的文档震惊了——“天哪,什么时候能看完”。其实这是一个错误的心态,这不是什么xxx入门书,你得看完之后才能入门。这就是一个文档、手册,把Tutorials看一遍就行了,剩下的就是随用随查,心情好的时候来搂两眼。不然的话心里包袱太重导致哪一章都看不下去。

Django文档的模块介绍

Django的文档基本上就这几个模块——Model layer, view layer, template layer, Forms, deployment process。

这几个模块的介绍顺序就是你项目开发的顺序,先定义Model,然后写view,最后渲染template。forms这部分通常情况下用的不多,最最后就是部署了。

Model 这一部分包含了所有你要和数据库打交道的内容,一般项目在一开始的时候都会先抽取实体,然后定义模型,所以这一部分在文档的开始。

从你开始定义Model中使用的字段,类型,到Model查询出得结果Queryset的介绍,以及Model这个对象实例化之后包含哪些方法都在这一部分了。

只要是和数据库相关的部分,遇到问题查这个应该就差不多了。

View 这一部分是在你定义好Model之后需要用到的。在view中的逻辑是接受浏览器发过来的request请求,也就是在view中常写的 def view(request): 。接受到这个Request之后,就是你自己的业务逻辑了,基本上也就是从Model中取出数据,然后对数据进行处理,最后通过Response返回给浏览器。

除了view内部的逻辑之外,在一个view被调用之前还有一个urlconf的配置,用来匹配对应的url到对应的view中。而在往上捣捣就到Middleware了,这一层的主要作用是处理接收到的Request和返回的Response。

剩下的也就是文件上传,数据导出之一类的东西。但凡是逻辑部分的东西,都在这部分能找到

Template 这个就是模板的基本使用,Django的模板本来就很简单,看看语法,看两个例子就行了。因为语法简单,所以可能会遇到满足不了需求的情况,这种情况下就需要自己扩展了,Django提供了Tags和Filter的接口,允许你编写自己的扩展。

常用的也就这几部分,等到项目开发的差不多需要部署的时候,需要再去看看 The development process 部分。如果需要用到Django自带的Admin的话,可以去看看The admin部分。其他的部分就是随用随取,当然更好的情况是自己有心情,走马观花的看看。

可能存在的捷径

无论是读翻译的中文文档,还是遇到问题时去搜中文的资料,你看到的任何一个材料其实都逃不了Django的官方文档。因此我们可能不需要绕太多的弯子来达到理解Django文档在说什么这一目的。

直接去看英文文档可能会是一个捷径。无论是翻译还是别人(或者我)写的关于Django某一点的应用,都会随着Django版本的更新变得不再实用。并且所有这些资料的最终来源都是在官方文档上,因此不如直接从源头上汲取营养。

另外还得说说英文阅读的事儿,这是任何开发人员都绕不过的坎,关于英文对程序员的重要性网上已经有很多论述了,我这里不再添加冗余的信息了。只说一句:如果你没有办法直接从源头上获取知识,那你就只能去等别人帮你消化完,这样的结果是你不但丧失了消化能力,还始终获得的是陈旧甚至被曲解过的知识。

两种实践方法

自己一个人看东西有时还是挺无聊的,单纯的阅读也是挺无聊的,那么当你陷入这种状态之后,怎么破呢?我个人总结了两种实践方法:

以练促读 通过练习来读文档,看的时候顺便写写代码,验证下文档是不是正确。这个方法相当的实用,别光看,动起来,实践出真知嘛。很多东西你以为自己读懂了,但真正用的时候还是糊里糊涂。就像是我之前写的那篇《从Django的Tutorials可以学到什么》一样,虽然以前就看过,但是不实践一次的话,还是没有什么感觉。

所以,以练促读对我来说是一个高效的,并且不太费时的方法。

以教促学 相对于上面的方法,这个以教促学的方法会花更多的时间。上面的方法只是自己明白,能够使用。这里的目的却是把别人也讲明白,这就需要把要讲的内容反反复复的仔细琢磨,然后转化为自己的方式、语言,传递给别人。

虽说耗时会多些,但收获是更多的。

总结

吧啦吧啦的写了一堆,也算是对自己的思路做一个整理。写这篇文章,其实就是在实践上面的 以教促学 这一方法,写文章的耗时要远多于我自己在脑海中构想Django的文档结构,但写出来才是真正的把构想实现。这也是我喜欢写博客缘由之一。

本文的主要是从自己的经验上来说的,仅供参考,也欢迎补充不同的方法和建议。

原文发布于微信公众号 - 马哥Linux运维(magedu-Linux)

原文发表时间:2014-12-23

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏信安之路

Red Team 工具集之信息收集

上图是一个 Red Team 攻击的生命周期,整个生命周期包括:信息收集、攻击尝试获得权限、持久性控制、权限提升、网络信息收集、横向移动、数据分析(在这个基础上...

1800
来自专栏嵌入式程序猿

我怼了硬件工程师,让你不按datasheet设计

最近有个项目是使用NXP的KEAZ64芯片,基于cortex M0+内核。带有mscan模块,mscan是NXP的8位机和低端32位上用的CAN模块外设,和我们...

3927
来自专栏BIT泽清

App Store审核成功解决2.1大礼包被拒后,通过最后一关的元数据被拒分享

最近这周帮一个客户上线一个棋牌游戏的项目,已经被3.2.1过后处理成功,又出现了2.1大礼包App完成度的问题;经过连续2天的加班通宵(当然是团队伙伴们车轮战拉...

1.3K9
来自专栏微服务

全面解读NoSQL数据库Redis的核心技术与应用实践

互联网和Web的蓬勃发展正在改变着我们的世界,随着互联网的不断发展和壮大,企业数据规模越来越大,并发量越来越高,关系数据库无法应对新的负载压力,随着Hadoop...

4056
来自专栏Java技术栈

Java开发必知道的国外10大网站

1、https://www.google.com/ ? 不解释 2、https://stackoverflow.com ? 里面包含各种开发遇到的问题及答案,质...

4427
来自专栏私有云搭建

腾讯云服务器+可道云kodexplorer打造企业私有云

公有云越来越疲软,企业用户和个人用户对于公有云的接受度也越来越低。企业用户往往转向私有云盘产品,个人用户往往转向了NAS产品,从而来满足自己对于文件共享和管理的...

1.2K5
来自专栏向治洪

Android Topeka介绍

概述 当你已经做Android开发一段时间,并苦于进入瓶颈,这个时候阅读一些优秀App的源码是最好的学习进阶方式,前几天,邀请去参加一个Android大会,我作...

2358
来自专栏杨建荣的学习笔记

SQL审核的整体设计和落地

SQL审核目前已做差不多了,整个过程其实看起来,要远比我们想的c/s服务调用要复杂的多。

2152
来自专栏携程技术中心

干货 | 携程图片服务架构

2296
来自专栏技巅

docker解决数据存储问题的方案

2547

扫码关注云+社区

领取腾讯云代金券