Documentation process

原文：https://docs.gitlab.com/ee/development/documentation/workflow.html

• Who updates the docs?
• Documentation labels
• How to update the docs
  • Reviewing and merging
• Other ways to help
• Post-merge reviews
  • Before merging

Documentation process

创建和维护 GitLab 产品文档的过程允许任何人提交合并请求或为 GitLab 文档创建问题.

注意：与新功能或功能增强相关的文档更新必须使用 GitLab 手册中描述的功能工作流程 .

Who updates the docs?

任何人都可以贡献力量！ 您可以在以下情况下创建文档合并请求：

• 您发现现有文档中存在错误或其他需要改进的地方.
• 您对全新文档有一个想法，可以帮助 GitLab 用户或管理员完成其与 GitLab 的工作.

Documentation labels

无论发布或合并请求的类型如何，添加或更新文档时都需要某些标签. 发行或合并请求作者添加了以下内容：

• 适当的类型标签 .
• 阶段标签和组标签 . 例如， ~devops::create和~devops::create ~group::source code .
• The ~documentation specialization label.

技术写作团队的成员还添加了以下内容：

• 具有docs::前缀的文档范围标签 . 例如， ~docs::improvement .
• The ~Technical Writing team label.

与新功能或更新功能的发布无关的文档更改不带有~feature标签，但仍需要~documentation标签.

它们可能包括：

• 创建或更新文档以提高准确性，完整性，易用性或功能更改以外的任何其他原因.
• 解决现有文档中的空白，或对现有文档进行改进.
• 处理与文档相关的特殊项目.

How to update the docs

要更新 GitLab 文档：

1. Either:
   • 单击https://docs.gitlab.com上任何页面底部的” 编辑此页面”链接.
   • 导航到GitLab 文档指南页面上列出的存储库和文档路径之一.
2. 请遵循页面上列出的描述的标准和过程，包括：
   • 结构和模板页面.
   • 样式指南 .
   • 降价指南 .
3. 遵循 GitLab 的合并请求准则 .

提示：如果您没有开发人员对 GitLab 项目的访问权限，请分叉工作.

如果您满足以下条件，请寻求技术写作团队的帮助：

• 需要帮助选择正确的文档位置.
• 想讨论文档想法或大纲.
• 想要请求其他帮助.

要寻求帮助：

1. 找到相关DevOps 阶段组的技术作家.
2. Either:
   • 如果需要紧急帮助，请直接在问题或合并请求中分配技术作家.
   • 如果需要非紧急帮助，请在问题或合并请求中 ping 技术作家.

如果您是 GitLab Slack 工作区的成员，则可以在#docs请求帮助.

Reviewing and merging

拥有维护者访问相关 GitLab 项目权限的任何人都可以合并文档更改. 维护者必须认真努力，以确保内容：

• 清晰易懂，易于目标受众浏览和理解.
• 符合文档指南和样式指南 .

如果作者或审稿人有任何疑问，他们可以提及被分配到相关DevOps 阶段小组的作者 .

该过程涉及以下内容：

• 主要审稿人. 由代码审阅者或其他适当的同事进行审阅 ，以确认准确性，清晰度和完整性. 对于较小的修订，可以跳过，而无需实质性的内容更改.
• 技术作家（可选）. 如果在合并之前未完成合并请求，则必须在合并后安排. 仅在需要紧急合并时才安排合并后审核. 要请求：
  • 合并前审查，为适用的DevOps 阶段组分配列出的技术作家.
  • 合并后审核，请参阅合并后审核 .
• 维护者. 对于合并请求，维护者：
  • 随时可以要求上述任何评论.
  • 在技​​术作家审查之前或之后进行审查.
  • 确保已设置给定的发布里程碑.
  • 确保应用了适当的标签，包括将合并请求选择到版本中所需的标签.
  • 确保（如果尚未完成或计划进行技术作家审查） 创建所需的问题 ，将其分配给给定阶段组的技术作家，并将其与合并请求链接.

该过程反映在” 文档 合并请求”模板中 .

Other ways to help

如果您有更多文档资源的想法，请使用”文档”模板创建问题 .

Post-merge reviews

如果在合并之前未分配给技术作家进行审核，则开发人员或维护人员必须在合并后立即安排审核. 为此，请使用” 文档审阅”描述模板创建一个问题，并从引入了文档更改的合并合并请求中链接到该问题.

可能会跳过常规的合并前技术作家审查的情况包括：

• 里程碑发布还有很短的时间. 如果还有不到三天的时间，请寻求合并后的审查，并通过 Slack 对作者进行 ping 操作，以确保审查尽快完成.
• The size of the change is small and you have a high degree of confidence that early users of the feature (for example, GitLab.com users) can easily use the documentation as written.

Remember:

• 在 GitLab，我们将文档视为代码. 与代码一样，必须检查文档以确保质量.
• 文档是 GitLab 对 done 的定义的一部分.
• 当代码在里程碑发布之前完成得很好并且需要更大的文档更改时，这种合并前的 Technical Writer 审核应该是最常见的.
• 如果重要的是尽快使它附带的代码合并，那么可以要求对文档进行合并后技术审查. 在这种情况下，原始 MR 的作者将在后续 MR 中阐述技术作家提供的反馈.
• 技术作家还可以帮助您确定无需技术作家审查就可以合并文档，而审查将在合并后立即进行.

Before merging

如果跳过初步的技术作家审查，请确保以下各项：

• 该产品徽章已应用.
• 包含引入该功能的 GitLab 版本已包括在内.
• 标题的更改不会影响应用内超链接.
• 记录了特定的用户权限 .
• 为了发现，这些新文档从更高级别的索引链接在一起.
• 遵循样式指南：
  • 用于目录和文件 .
  • 对于图像 .

注意：更改文档位置的合并请求必须在合并之前始终由技术作家审查.