Yuguo.us

谈谈项目文档

Introduction

user

余果

全栈工程师,《Web全栈工程师的自我修养》作者。


Featured

back-end

谈谈项目文档

Posted by 余果 on .

我认为好的项目文档需要满足两个要求:

  • 只需要较少的额外工作量
  • 文档和代码要保持一致

案例:

用一个wordpress搭建项目文档

用一个wordpress搭建项目文档平台同时违反了这两个要求:

  • 开发者需要登录wordpress,然后在糟糕的WYSIWYG编辑器中编写文档、用例、作者等。这需要很大的额外工作量。
  • 当项目变化的时候,开发者不会记得更新wordpress,所以文档和code之间出现了不一致,这种不一致最终会积累的越来越多,以至于文档变得完全不具有参考性,没有人会再去查阅它。

但是用wordpress管理一些与代码无关的文档的时候是比较适合的,比如环境搭建,新人指引都是不错的。

用json记录代码信息

本周的例会有一个小朋友分享了他做的一个工具,无需服务器环境,JavaScript会把代码库中的所有文件的信息抓取出来放在一个页面上方便展示。但是这些信息需要用json文件来在每个文件夹下录入。

我们可以看到这种方法也同时违反了这两个要求:

  • 需要编辑json文件,这需要较多的工作量。
  • 项目变化的时候,开发者不会记得更新json文件。开发者没有足够的动机来更新它,因为熟练的开发者会用编辑器直接定位到文件,不会使用这个工具,新人不了解代码环境,会被错误的json信息误导。

用PHP抓页面信息

我之前做过一个开源小工具spider(https://github.com/yuguo/spider),目的是管理项目中所有页面都会使用的公共组件。

项目背景:我们有一些静态组件(HTML+CSS)需要在全站点使用,我们希望尽可能地鼓励新人和旧人都来使用这些组件,以节省人力,保持一致。

需要环境:PHP

原理:spider会抓取符合规则的html文件(规则可以有路径、html命名规则等,用正则表达式实现),然后抓取html的名字、作者、描述(这些通过标准meta值取得)、最后修改时间(PHP取得)、缩略图(手工配置,可选),并最终在一个页面上全部展示出来。

性能:无数据库,有缓存

这种方法我个人觉得还是比较不错的:

  • 工作量较小,仅需要修改html头部信息
  • 变化的时候也比较容积记得更新

我在本项目部署好了之后把入口开发给大家使用,后来兄弟项目也把代码部署过去实现了另一个公共组件聚合,效果还是不错的。

user

余果

https://yuguo.us

全栈工程师,《Web全栈工程师的自我修养》作者。