技术文档标准之实时更新与准确

背景

在软件产品研发过程中，技术文档尤其重要（包括系统架构文档、技术方案文档），技术文档的管理和维护是一项至关重要的任务。(目前挺缺乏)

合理规范化的管理文档，不仅可以帮助团队成员理解系统设计和技术方案，还为未来的维护和扩展提供了重要参考，对于新入职或新加入的同学有很好的指导意义，而不是在一堆可能过期的、无人维护的文档或者项目代码中去了解目前的系统状况。

在目前，随着产品项目的迭代与发展，一些技术方案或系统架构往往会在一点一点慢慢发生变化，最终造成现状是文档管理十分混乱的。

这会导致技术文档容易过期变成废弃的文档，给团队协作和项目进展带来很多的挑战。为了解决这一问题，我们需要思考并整理出相对系统的文档管理的规范，确保技术或架构文档的及时更新以及相对准确性。

管理

目标是确保技术方案和系统架构文档的及时更新和准确性，通过集中管理、版本控制、或自动化更新、定期审查与清理、标准化整个文档流程来实现。

集中

存储

目前架构图大家都会集中在某个文档中管理，但是缺乏一些更新机制

• 存储：将所有架构图或技术文档集中存储在一个专门的Confluence空间中，不仅便于集中管理和更新，也有助于团队成员快速找到所需的信息。可以创建一个“XX业务架构文档”的目录，统一存放所有相关文档
• 结构：在Confluence中需要采用相对清晰的目录结构，根据业务模块或功能进行分类存储，确保每个文档都有明确的位置，便于查找和管理

版本

• 版本控制：利用Confluence的版本控制功能记录每次文档更新的历史。这样可以追踪到每个版本的变更，确保每次更新都有记录可查
• 外部版本控制：我们会通过很多工具去画我们架构图，比如PlantUML或者Draw.io，我们将PlantUML和Draw.io源文件文件保存在Git等版本控制系统中，便于与代码同步管理。通过Git的提交记录，可以清晰了解每次架构图变更的具体内容和时间。（是有必要的，否则源文件只会存在最初画图的同学电脑中）

更新

工具

PlantUML

我们在画很多软件开发过程设计图，可以运用PlantUML，并使用PlantUML和Confluence集成，使用Confluence插件可以直接在Confluence页面中嵌入PlantUML代码。这可以避免手动导出和上传图片的步骤，确保每次代码更新时架构图也自动更新。

Draw.io

Draw.io来画相关架构设计图或系统结构图，可以使用Draw.io和Confluence集成：使用Draw.io的Confluence插件，直接在Confluence页面中创建和编辑图表。这将消除手动导出和上传图片的步骤，并确保架构图的实时更新。

自动化脚本

当然这一步是更进阶的管理方式，编写脚本通过gitlabCI控制系统中的PlantUML和Draw.io文件，自动生成最新的图片并更新到Confluence中（后续可以考虑）

定期审查

定期审查

制定定期的文档审查计划，例如每月或每季度一次。自主安排专门的文档审查，由文档负责人或技术负责人来负责检查和更新架构图和技术方案，确保其内容准确、最新

即准备详细的审查清单，列出所有需要检查的文档，检查其内容是否准确、是否有过期信息、是否需要更新

过期清理

在定期审查技术方案，会存在系统下线或者业务不在运营的情况，需要标记和归档过期的文档

在Confluence中清晰地标注这些文档为“已过期”或“历史版本”，并移动到专门的归档区域，确保团队成员能够区分最新文档和历史归档文档

统一模板

目的是为了规范大家的文档，如何写技术文档，目前已有好的规范，需要在执行中来落实

一、背景 1.1 项目背景 1.2 项目目标 1.2.1 业务目标 1.2.2 技术目标 二、方案调研 三、总体设计 3.1 名词解释 3.2 架构与约束 3.2.1 用例图 3.2.2 系统架构图 3.2.3 实体关系图 3.2.4 存储模型图 3.2.5 核心流程图 3.2.6 状态机模型图 四、详细设计 4.1 XX 4.2 XX 五、稳定性保障 5.1 风险点 5.2 埋点&异常处理 六、外部接口 七、工时排期

实践

更新流程

在每月初审阅，审阅架构图补充或修订相关系统变化，技术负责人在“架构图存储库”空间中更新架构图，记录变更内容和版本号，生成内容最新版本并发布到Confluence。

每月中旬空间文档负责对文档进行标注，并组织审查会议，检查并更新过期的技术方案，记录审查结果和更新日志，标注“已过期”或“历史版本”，并通知团队成员，确保所有人都能获取最新的文档信息。

总结

我们需要系统地管理架构文档和技术方案，确保其及时更新和准确性，这样不仅可以提升了团队的协作效率（便于新人快速熟悉现有系统），还能为项目后续发展迭代提供了文档基础（为后续架构调整能快速了解现有系统），也希望通过实践能为文档管理过程中提供有益的参考吧