galaxyyao / dev-doc-library-template

通用开发文档库模板

通用开发文档库模板

这是一个通用的研发团队文档库的模板。

作用

对于研发团队，文档库有利于：

• 对新加入的成员提供指引
• 方便开发测试过程中随时随地查找资料
• 方便团队内部信息和知识共享
• 提供审计用开发资料

常用文档库软件

Gitlab本身是一个不错的文档库平台。但存在几个缺陷：

• 无法自动生成目录或索引
• 界面还不够友好
• 跨文件搜索内容比较麻烦
• 大文件渲染速度略慢

建议配合Gitlab CI/CD pipeline与MkDocs，自动生成静态页面。具体方案可以参见我的博客。

整体目录结构

整体目录结构按以下方式划分：

• 新人指引：新加入团队的员工参考，包含开发测试环境准备，团队内通用的开发测试工具及下载地址等
• 开发规范：包含通用的版本管理、代码提交、接口设计、各语言开发规范，以及数据库开发规范。本模板包含一份Java语言的规范作为参考（内容参考阿里Java开发规范）
• 项目文档：各项目的开发资料与环境配置
• 开发手册：包含工具类与开发框架的使用指南等
• 技术文章：团队成员的技术研究分享

其中项目文档目录也包含了一份模板，可以作为新项目创建时的基准。