DevOps 正在以前所未有的速度挑战 IT 历史中的技术文档规范。从自动化到提高交付速度，再到打破瀑布软件开发生命周期模型，所有这些都意味着需要对业务和技术文档的理念进行重大变革。
以下是 DevOps 如何影响技术文档的一些方式。
技术文档撰写者不断变化的角色
技术文档撰写者的角色必须适应 DevOps。好消息是，许多技术文档撰写者已经嵌入到开发团队中，他们可能已经通过建立协作关系和增长的产品知识而占据优势。
但是，如果您的技术文档撰写者习惯于在孤岛中工作，并依赖主题 matter 专家编写的草稿作为文档的基础，那么您就需要进行一些调整。
进行投资，以确保您的文档和其他项目相关的内容开发工作获得所需的工具、结构和支持。首先改变您的技术文档撰写者招聘实践。DevOps 速度的文档需要重新思考您的内容策略，并打破 DevOps 团队与分配支持该项目的技术文档撰写者之间长期存在的壁垒。
DevOps 也导致开发团队摆脱传统文档实践的束缚。最重要的是，文档的完成定义必须改变。一些企业文化使技术文档撰写者成为软件开发中的被动参与者。DevOps 提出了新的要求——随着 DevOps 文化转型的发展，技术文档撰写者的角色也在发展。撰写者将需要（并且必须适应）DevOps 提供的透明度。他们必须融入 DevOps 团队。根据组织如何定义角色，将技术文档撰写者引入团队可能会带来技能挑战。
文档标准、方法和规范
虽然 DevOps 尚未影响技术文档本身，但开源社区已挺身而出，帮助应用程序编程接口 (API) 文档，这些文档正在各种规模的企业中的 DevOps 团队中得到应用。
用于记录 API 的开源规范和工具是一个令人兴奋的关注领域。我认为这归功于Google Season of Docs 的影响，该计划使开源软件项目能够获得专业的 technical writing 人才，以解决他们最关键的文档项目。
开源 API 是可用的，并且需要成为 DevOps 文档讨论的一部分。云原生应用程序集成需求的重要性正在上升。OpenAPI 规范——一种用于定义和记录 API 的开放标准——是 DevOps 环境中 API 文档的良好资源。然而，一个重要的批评是，该规范可能会使文档创建和保持最新状态非常耗时。
曾经短暂尝试创建持续文档方法。还曾经出现过创建 DocOps 框架的运动，该框架来自 CA（现为 Broadcom）。尽管 DocOps 最初前景光明，但它从未成为行业运动。
DevOps 文档标准的现状意味着您的 DevOps 团队（包括您的技术文档撰写者）需要在项目的最早阶段开始创建文档。您可以通过将文档添加为敏捷故事和（同样重要的）管理期望来实现此目的；您可以通过将其与年度绩效考核联系起来来强制执行它。
文档工具
DevOps 文档编写应在线进行，格式或平台应所有团队成员都可访问。MediaWiki、DokuWiki、TikiWiki 和其他开源 wiki 为 DevOps 团队提供了一个集中的存储库，用于编写和维护文档。
让团队选择他们的 wiki，就像您让他们选择他们的其他持续集成/持续开发 (CI/CD) 工具链一样。开源 wiki 的部分力量在于其可扩展性。例如，DokuWiki 包含一系列扩展，您可以安装这些扩展来创建满足您的 DevOps 团队编写要求的编写平台。
如果您有雄心壮志地增强团队的编写和协作能力，Nextcloud（一个开源云协作套件）是让您的 DevOps 团队在线并为他们提供编写文档所需的工具的一种选择。
DevOps 最佳实践
文档在 DevOps 转型中也发挥着作用。您将需要记录帮助您的组织从 DevOps 中实现效率和流程收益的最佳实践。此信息非常重要，不能仅通过 DevOps 团队之间的口头传播来传达。如果您的组织有多个 DevOps 团队，文档是一种统一的力量；它可以促进最佳实践的标准化，并使您能够捕获和基准化代码质量指标。
通常，是开发人员承担记录 DevOps 实践的工作。即使他们的组织有技术文档撰写者，他们也可能跨开发团队工作。因此，开发人员和系统管理员能够捕获、记录和传达他们的最佳实践非常重要。以下是一些使这项工作朝着正确方向发展的技巧
- 预先投入时间来创建 DevOps 最佳实践的标准模板。不要陷入复制您在网上找到的模板的陷阱。采访您的利益相关者和团队，以创建满足您的团队需求的模板。
- 寻找在信息收集方面发挥创意的方法，例如记录您的团队会议并使用聊天系统日志作为文档的基础。
- 建立一个 wiki 来发布您的最佳实践。使用一个 wiki，让您可以维护编辑和更新的审计跟踪。这样一个平台使您的团队能够随着最佳实践的变化而更新和维护它们。
在构建 CI/CD 工具链时，记录依赖项是很明智的。当您让新团队成员入职时，这种努力会得到回报。当团队成员忘记某些事情时，这也是一点保险。
最后，自动化对 DevOps 利益相关者和实践者都很有吸引力。在自动化崩溃之前，一切都很有趣。为自动化运行手册、管理员指南和其他内容准备好（并保持最新）文档意味着您的员工可以使自动化再次工作，无论它何时崩溃。
最后的想法
DevOps 对技术文档来说是一个净收益。它将内容开发拉入 DevOps 生命周期，并打破组织文化中开发人员和技术文档撰写者之间的壁垒。在没有技术文档撰写者的有利条件下，团队可以获得加速文档编写速度的工具，以匹配 DevOps 的速度。
您的组织正在做些什么将文档引入 DevOps 生命周期？请在评论中分享您的经验。
2 条评论