API文档管理工具折射出的技术视野
什么是技术视野 网上看到不少关于如何提升技术视野的讨论,但却没有人给出定义,到底什么是技术视野? 所谓技术视野,就是看问题时所能切换的不同角(维)度。 下面就以API管理工具(以下简称“管理工具”)为例,来探讨背后隐藏的技术视野。 API管理工具 零视角 曾经在一个小型创业公司用到过最简单的管理工具,就是一个开源的文档管理工具,界面功能类似wiki(维基百科)。 这样的工具确实能满足核心需求——API在线文档化,并支持用户管理。 可是深想一层,对于管理工具的使用者——工程师,操作足够友好,功能足够完善吗? 使用这类管理工具很多时候都会出现文档与代码不一致的情况,也就是说工程师都不愿意去维护这个文档。 因为编写修改文档是个耗费时间的事情,短期来看, 维护了既无利益,不维护也无危害~ 所以有时候接口的变更通过口头协商而非文档协商。 小结:零视角其实谈不上视野,是大多数工程师的最容易形成的思维方式,特点就是只关注功能/问题本身。 单一视角 当时为了解决上面的问题,同时为了练手所学的Node.js,我写了第一版的管理工具,并参加了线下沙龙分享。 现在看来其实当初的写的项目还是比较粗糙的,除了展示界面相较于wiki更加美观之外,主要加入了 Mock 功能。 更好的开源项目也有不少,比如阿里的 RAP 和国外的 APIDOC 。 之所以把它们归为一类讨论,那是因为它们都体现了开发者的单一视角。