微服务架构下文档管理规范
如果使用微服务架构进行应用开发，微服务的开发过程中，会产生许许多多的文档，其中包括需求文档、设计文档、开发文档、测试文档、运维文档以及各种项目管控文档。而且微服务的开发，一般都会引入敏捷的开发模式，虽然敏捷倡导“个体和互动高于流程和工具，工作的软件高于详尽的文档”，但并不是说文档资料不重要，而是精简规范文档高于繁复套路文档，精简规范实用性较强的文档，是提高企业或团队整体交付及创新能力的基础。
因此，文档资产的管理在软件的研发过程中，是非常重要的，那么如何对文档进行更高效的管理，一般需要从以下几个方面进行规范化管控：目录结构、文档命名、文档格式。
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倍；
其他的一些规范，建议以实用为主，但不能大白话。