微服务架构下文档管理规范

　　如果使用微服务架构进行应用开发，微服务的开发过程中，会产生许许多多的文档，其中包括需求文档、设计文档、开发文档、测试文档、运维文档以及各种项目管控文档。而且微服务的开发，一般都会引入敏捷的开发模式，虽然敏捷倡导“个体和互动高于流程和工具，工作的软件高于详尽的文档”，但并不是说文档资料不重要，而是精简规范文档高于繁复套路文档，精简规范实用性较强的文档，是提高企业或团队整体交付及创新能力的基础。

　　因此，文档资产的管理在软件的研发过程中，是非常重要的，那么如何对文档进行更高效的管理，一般需要从以下几个方面进行规范化管控：目录结构、文档命名、文档格式。

1.目录结构规范

　　对于有大量文档的项目，文档分类的目录结构有着举足轻重的作用，好的文档目录结构是能够起到自说明的作用（类似于开发中，好的程序包名是能够进行自说明业务模块），因此，目录结构的规范，建议按照项目、阶段、模块等进行划分。建议参考如下文档目录结构规范：

├─XXX项目A

│  ├─01.项目准备

│  ├─02.需求分析

│  │  ├─01.用户故事

│  │  └─02.故事清单

│  ├─03.需求设计

│  │  ├─01.总体设计

│  │  ├─02.概要设计

│  │  ├─03.详细设计

│  │  ├─04.原型设计

│  ├─04.需求开发

│  ├─05.需求测试

│  │  ├─01.单元测试

│  │  ├─02.集成测试

│  │  ├─03.功能测试

│  │  └─04.性能测试

│  ├─06.项目上线

│  │  ├─01.上线准备

│  │  └─02.上线培训

│  ├─07.项目运维

│  │  ├─01.环境信息

│  │  ├─02.操作手册

│  │  ├─03.运维手册

│  │  └─04.应急手册

│  ├─08.实践经验

│  │  ├─01.经验总结

│  │  └─02.最佳实践

│  └─09.项目管理

│      ├─01.项目计划

│      ├─02.项目周报

│      └─03.会议纪要

└─XXX项目B

   ├─01.项目准备

   ├─02.需求分析

2.文档命名规范

　　对文档管理的目录进行规范化之后，需要对文档的命名进行规范化，文档的命名一般建议采用三阶段命名：

　　建议命名规范：{公司简称}_{系统|产品全称}_{文档核心用途}.{文档后缀}

　　例如：普元金融_DevOps平台_用户操作手册.pdf

　　第一阶段：说明文档的归属，一般建议为公司的简称，例如：普元金融、阿里巴巴等。

　　第二阶段：说明文档的所属产品或项目，一般建议以项目的全称，例如：个人网银系统、企业服务总线系统等。

　　第三阶段：说明文档的核心名称，例如：用户操作手册、服务管理规范等。

　　第四阶段：一般为文件的版本信息，可省略（由于目前大多数的文档库管理软件，均已实现多版本管理，已无需在文档的命名上添加版本信息，例如：gitlab等）。

3.文档格式规范

　　作为一个阅读者而言，一个文档是否能够阅读下去，首先应该是文档的格式，其次才是文档的内容，因此对于文档的内容，那是专业层次的内容，在规范层面不进行阐述，本文只针对文档的格式进行规范化。

　　文档格式的规范化，应该从首页、目录、版本信息、阅读对象、页眉页脚、以及字体等进行规范化：

　　首页：文档的首页可以有封面，也可以没有封面，首页主要阐述文档的基本信息，如：文档名称、文档作者、编写时间、保密级别等信息；

　　目录：文档的目录起到索引的作用，建议文档的目录到文档的三级菜单，并且超链接页码；

　　版本信息：文档的修订记录，何时、何人修改了何内容，版本建议三位数组成，建议版本规范：V1.0.0，第一位：代表主版本，第二位代表审批版本，第三位代表修改版；

　　页眉页脚：页眉主要用于说明文档的章节或文档的密级，页脚主要用于描述文档的页码及版权信息；

　　阅读对象：本文档的面向用户，在面向用户部分，需要简单说明面向用户需要储备的知识；

　　字体规范：正式的文档，一般建议采用宋体、仿宋或微软雅黑中的一种，整个文档建议采用同一种字体，并且字体的正文建议采用小四；

　　段落行距：段落需要缩进2个字符，行间距建议为1.5倍；

　　其他的一些规范，建议以实用为主，但不能大白话。