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

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

案例：

用一个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头部信息
• 变化的时候也比较容积记得更新

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