title: “建立工作流”
description: “如何借助 docmd 与"文档即代码"原则，搭建一套高速的多人协作文档工作流。”

问题

团队若没有结构化的工作流，更新就会被延误或遗忘。缺乏清晰流程会导致内容碎片化、格式不一致。技术作者花在解决合并冲突上的时间，甚至比写高质量内容还多。

为什么重要

没有正式流程，文档很快就会过时。如果文档更新必须等待缓慢的软件发版周期，那么指南就会与产品功能长期脱节。这会带来用户挫败感，并推高支持工单量。

方法

将文档部署与软件发版周期解耦。沿用软件开发中成熟的流程：分支 → Pull Request → CI/CD 预览。docmd 本身非常轻量，能让团队以极低的开销实现"文档即代码 (docs-as-code)"。

实现

1. 仓库策略

请选择最契合您组织结构的策略：

• Monorepo 策略：在主应用仓库中保留 /docs 目录。这样，文档改动能与所描述的代码改动合并到同一个 Pull Request 中。
• 独立仓库策略：适合大型组织或开源项目，由专门的团队独立管理文档。

2. 使用 CI/CD 进行校验

将 docmd 接入 CI/CD 流水线，确保每次更新在技术上都正确无误。流水线至少应运行构建命令，以检查语法错误和配置问题。

# 在 GitHub Actions 中的校验示例步骤
- name: Validate Documentation
  run: npm install && npx @docmd/core build

详细的设置说明请参阅 GitHub Actions 指南。

3. 协作评审流程

为所有文档更新建立同行评审文化。通过 Pull Request 讨论变更、核验格式、确保技术准确性。使用 Threads 插件 让讨论直接发生在已渲染的内容上。

取舍

采用"文档即代码"工作流，可能对非技术贡献者构成门槛 —— Git 与 Markdown 可能会让他们感到畏惧。为缓解此问题，可以在简单修改时使用 GitHub 内置的网页编辑器；也可以使用 实时预览 功能提供更直观、可视化的写作体验。