问题

在大型团队中，每个技术作家都有不同的风格和偏好。有些人可能使用加粗文本进行强调，而另一些人则使用斜体。有些人可能更喜欢“点击按钮”，而另一些人则使用“选择选项”。随着时间的推移，您的文档可能会变成各种冲突风格的“百纳被”，使用户难以快速解析信息，并降低了产品的专业信任度。

为什么重要

一致性孕育熟悉感。当用户学习复杂的 API 或工作流时，他们依赖一致的词汇和结构模式来有效地浏览内容。统一的声音使您的文档感觉像是一个连贯的、高质量的产品，从而建立了对软件本身的信心。

方法

使用 标准化容器 和自动化 Lint 工具进行机械式的一致性强制执行。通过自动化低层级的风格和语法检查，您可以让编辑人员腾出精力，专注于内容的高层级质量、准确性和清晰度。

实施

1. 使用标准化的 docmd 模式

鼓励所有贡献者使用 docmd 内置的主题化容器，而不是即兴使用手动 Markdown 格式。这确保了整个站点中的每一个警告、提示或说明在外观和行为上都是一致的。

<!-- ❌ 避免：不一致且无样式 -->
**注意：** 请重启服务。

<!-- ✅ 推荐：一致、无障碍且具有主题感 -->
::: callout info
请重启服务。
:::

使用 标注 (Callouts) 可确保您的文档保持专业外观并符合无障碍标准，而无需作者付出额外努力。

2. 实施散文 Lint 检查

集成 Vale 或 Markdownlint 等工具来强制执行品牌术语、语气和语法。这些工具可以配置为自动检查被动语态、偏见语言或不正确的品牌拼写。

# .vale.ini 示例
MinAlertLevel = suggestion
Packages = Google, Microsoft
[*]
BasedOnStyles = Vale, Google

3. CI/CD 中的自动化强制执行

在您的 GitHub Actions 或其他 CI/CD 流水线中包含一致性检查。这确保了每个拉取请求 (Pull Request) 在合并之前都会自动进行风格和结构一致性审计。

# Lint 检查的 CI 步骤示例
- name: Lint Documentation
  run: vale docs/

权衡

如果社区贡献者在修复简单的拼写错误时遇到了多个“风格错误”，严格的 Lint 检查有时会打击他们的积极性。我们建议将外部贡献的 Linter 敏感度设置为 warning（警告），并为内部团队更新保留 error（错误）状态，以在一致性与包容性之间取得平衡。