Documentation process

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

Documentation process

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

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

Who updates the docs?

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

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

Documentation labels

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

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

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

它们可能包括:

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

How to update the docs

要更新 GitLab 文档:

  1. Either:
  2. 请遵循页面上列出的描述的标准和过程,包括:
  3. 遵循 GitLab 的合并请求准则 .

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

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

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

要寻求帮助:

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

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

Reviewing and merging

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

如果作者或审稿人有任何疑问,他们可以提及被分配到相关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 版本已包括在内.
  • 标题的更改不会影响应用内超链接.
  • 记录了特定的用户权限 .
  • 为了发现,这些新文档从更高级别的索引链接在一起.
  • 遵循样式指南:

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