DevOps中文档的最小编写规范
背景
近来DevOps在开发界和运维届大行其道，尤其适用于持续交付的场景。可以在满足最小需求的条件下快速上线应用，得到用户反馈后持续迭代功能，直至达到理想中的效果。
DevOps存在大量的开源项目，比如Jenkins、GitLab CI/CD、Docker、Kubernetes、Istio，等等；虽然有了这么多的工具，但是若想实现DevOps，依然不是一件容易的事情。把各个工具搭建起来形成一个可用的体系，是一个很复杂的过程；这里面会涉及到各个工具的版本选择、协同工作，以及很多的权限设置，等等。
在实际的工作过程中，发现团队中的文档储存量聊胜于无，导致了一系列问题。
主要暴露的问题
这里就几个比较明显的问题做一下简单的描述：
搭建的环境不一致
因为没有文档的约束，各个工程师（甚至同一个工程师在不同的时间段）在搭建环境时会根据自己的喜好搭建工具，比如：安装软件到不同的位置；使用不同版本的依赖库；选择不同的插件列表进行安装；选择不同的权限配置，等等。
出现问题时追溯困难
主要包括两种问题：1）线上bug或性能问题，当出现bug或者性能遇到瓶颈时，需要从各方面排查问题，如果没有安装文档，则很难追溯bug出现的原因；假如遇到性能问题进行调优，从宏观层面也无法快速断定调优的边界，只能由当事人（环境搭建者）人肉诊断。2）升级的问题，有些工具的升级至涉及到核心程序的升级，对依赖库的版本没有要求，如果没有文档，无法界定核心程序与其依赖库的边界，容易造成冗余的操作或升级失败。
交接困难（寻找backup人选困难）
搭建环境的当事人不可能24小时在线，更甚者在岗位变动或人员变动时，如果没有好的文档储备，会大大增加其他人对环境的运维。
增加自动化实践的成本
DevOps中的很多环节可以通过代码逻辑实现自动化，包括环境搭建、持续集成、应用部署等，尽可能减少沟通成本。这种自动化的实现是一个漫长的过程，这就更需要一份好的文档作为基础的规范材料，把其中的步骤抽象成代码逻辑，既能追溯实现，又能保证速度。
其他问题
比如新技术推广材料、新人培训材料等的编写缺少可靠的参考材料。
最小文档实践
最小文档5要素
由于DevOps技术栈繁杂，每个工具都很新且包含搭建、配置、定制化等方面的使用。一个新工具的引入一般会首先由一个小的团队进行技术预研，首先在测试环境搭建一套服务进行试用，而在试用过程中如果发现功能未达到预期，可能会放弃对此工具的使用。这种情况下不可能要求预研团队编写完备的文档，但是为了保证能顺利完成新技术从预研到投入使用（或者淘汰使用）的过程，需有一个最小文档的支撑，根据经验，包含下面几项：
- 搭建环境的选择记录，并说明为什么选择这种配置（比如机器性能、网络等）；
- 选用工具的版本，并简单说明选择的依据；
- 搭建的基本步骤，包含基本的资源创建操作命令（如
useradd; mkdir）、搭建路径、搭建过程中所使用脚本或配置文件； - 配置文件，简单说明每个配置项的含义及设置值的考量初衷；
- 后期运维（包括事故、小范围升级、配置修改等）的记录。
最小文档维护工具
考虑到时间和精力问题，在整个过程中可以不必考虑文档的质量，完全可以考虑以“流水账”的形式记录。而为了能便于维护，推荐使用Git进行这些文档的管理。
为了便于展示和分享最小文档，建议使用markdown编写文档，这样便很容易使用GitLab把文档通过web页面的形式进行查看，且能够查看每一次文档修改的记录，免去文档更新后老版本内容丢失的风险。
