问题

使软件发布与相应的文档更新保持同步是一项重大的协作挑战。通常情况下，文档在实际代码部署之前就已经在站点上更新（这会误导当前用户），或者在软件发布几天后才延迟更新（这会让早期采用者感到沮丧）。

为什么重要

软件行为与其文档之间的脱节是导致开发者产生挫败感的主要原因。为了使文档有效，它必须严格映射到用户当前运行的软件特定版本。为每个版本提供正确的上下文，可确保顺畅的入门和故障排除体验。

方法

使用 docmd 的 版本控制引擎 隔离活跃开发中的文档。这允许您的团队在一个单独的目录（例如 docs-next/）中异步编写即将发布的功能的内容，并仅在正式软件发布时才将其提升为“稳定”或“当前”状态。

实施

1. 组织您的目录

在主 docs/ 文件夹中维护稳定的文档，并为即将发布的版本创建一个专用目录。

项目根目录/
├── docs/       # 当前稳定版 (v1.x)
├── docs-v2/    # 即将发布的版本 (v2.0)
└── docmd.config.js

2. 配置版本

在配置中注册这两个版本。您可以将即将发布的版本标记为“Beta”或“Next”，以通过版本切换器向用户发出状态信号。

// docmd.config.js
export default {
  versions: {
    current: 'v1.0',
    all: [
      { id: 'v1.0', dir: 'docs', label: 'v1.x (稳定版)' },
      { id: 'v2.0', dir: 'docs-v2', label: 'v2.0 (Beta)' }
    ]
  }
};

3. 提升流程

当您准备正式发布新版本时：

1. 更新配置：将 docmd.config.js 中的 current 版本 ID 更改为 v2.0。
2. 更新标签：从 all 数组的 label 中移除“(Beta)”标签。
3. 存档旧文档：在 all 数组中保留 v1.0 条目，以便使用旧版本的用户仍然可以访问相关的文档。

权衡

维护开销

维护多个版本的文档需要严谨的态度。如果在稳定版本中修复了关键的拼写错误或安全警告，请确保该修复也应用到即将发布的版本目录中，以防止在新版本发布时出现“回归”问题。

SEO 与搜索

多个版本偶尔会导致搜索结果指向旧文档。使用 seo 插件和正确的规范 (canonical) 标签，确保“当前”版本始终被搜索引擎优先考虑。有关管理过渡的更多信息，请参阅 处理重大更改。