利用您的 DevOps 工具链将文档转化为有价值的信息来源
您多久处理一次很快就会过时的文档?一旦设计或文档被基线化,文档通常会偏离它所描述的系统,将其视为您不能再信任的信息源。
在系统和技术快速发展的时代,我们的设计和文档方法仍然停滞不前。
记录 AS-IS 架构很困难……但并非不可能。
它始于人和过程,而不是工具和技术。
在不解决人员和流程因素的情况下采用新的优秀工具不太可能产生任何改进。
人员和流程:先决条件
团队凝聚力:团队必须与共同目标保持一致,并且能够有效沟通。最初,谨慎的做法是安排定期的电话会议,以确保计划按计划进行。
确定每个信息区域的内容编辑器——例如:开发人员入职培训、API 目录、数据。
定义并同意轻量级流程;避免孤立地这样做,以确保团队接受新的工作方式
定义模板、指南和简单的分类法。
整合或(如果可能)更改现有流程。许多企业抵制变革,因此如果您不能说服现任者放弃旧式 TOGAF 模板,您可能需要发挥创造力。
采用软件工程思维
在进入市场寻找新的知识管理工具之前,为什么不评估您已经进行的投资呢?DevOps 工具链可以提供您需要的一切:使用 Markdown 的内容创作、使用 GIT 拉取请求的批准工作流、使用管道的质量控制和开箱即用的内容查看器。
您甚至可以将内容发布到静态站点。许多产品供应商为他们的外部文档这样做。例如,据我了解,Microsoft 的大部分文档都是在 GitHub 中创作和管理的。
来源:github.com/MicrosoftDocs →目标:docs.microsoft.com
下图描述了一个利用 DevOps 工具链的简单内容创作工作流程。
概述
作者为他们的新内容更改创建了一个本地分支。他们使用自己选择的 IDE(例如 VSCode)来创建 Markdown 文件。VSCode 还包括 DrawIO 等图表工具的扩展,因此您甚至可以对图表进行版本控制!
作者将分支发布到源代码控制管理系统中。从技术上讲,他们不需要一直这样做,但这是一种很好的做法,因为它提供了备份。
一旦作者准备好提交他们的内容更改以供批准,他们就会创建一个合并请求 (PR)。
内容编辑器将收到通知,通知他们有新的 PR。编辑将审核内容并决定批准或拒绝投稿;他们可以对新的/更改的内容添加评论,以便作者知道批准所需的内容。
创建/更新 PR(根据反馈)后,自动化管道将对内容执行各种质量检查。
一旦编辑批准了 PR,就可以将内容合并到主分支中。
来自主要分支的内容可以使用 DevOps 平台(例如 Azure DevOps WIKI)呈现给用户。
最后的想法
创建和管理质量文档并非不可行。最大的挑战是解决人员和流程因素。
大多数人看不到文档的价值,因此您需要拿出一些奖励并让团队参与进来。
定义并在可能的情况下使流程自动化——这可能包括审批部门;自动质量检查,例如拼写和语法;外部内容发布,例如 WIKI 和开发人员门户。
与任何系统一样,从简单开始,然后随着时间的推移添加/更改功能。
我希望你觉得这很有趣。