571.md

# Documentation process

> 原文：[https://docs.gitlab.com/ee/development/documentation/workflow.html](https://docs.gitlab.com/ee/development/documentation/workflow.html)

*   [Who updates the docs?](#who-updates-the-docs)
*   [Documentation labels](#documentation-labels)
*   [How to update the docs](#how-to-update-the-docs)
    *   [Reviewing and merging](#reviewing-and-merging)
*   [Other ways to help](#other-ways-to-help)
*   [Post-merge reviews](#post-merge-reviews)
    *   [Before merging](#before-merging)

# Documentation process[](#documentation-process "Permalink")

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

**注意：**与新功能或功能增强相关的文档更新必须使用 GitLab 手册[中](https://about.gitlab.com/handbook/engineering/ux/technical-writing/workflow/#for-a-product-change)描述的[功能工作流程](https://about.gitlab.com/handbook/engineering/ux/technical-writing/workflow/#for-a-product-change) .

## Who updates the docs?[](#who-updates-the-docs "Permalink")

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

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

## Documentation labels[](#documentation-labels "Permalink")

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

*   适当的[类型标签](../contributing/issue_workflow.html#type-labels) .
*   [阶段标签](../contributing/issue_workflow.html#stage-labels)和[组标签](../contributing/issue_workflow.html#group-labels) . 例如， `~devops::create`和`~devops::create` `~group::source code` .
*   The `~documentation` [specialization label](../contributing/issue_workflow.html#specialization-labels).

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

*   具有`docs::`前缀的文档[范围标签](../../user/project/labels.html#scoped-labels-premium) . 例如， `~docs::improvement` .
*   The `~Technical Writing` [team label](../contributing/issue_workflow.html#team-labels).

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

它们可能包括：

*   创建或更新文档以提高准确性，完整性，易用性或[功能更改](https://about.gitlab.com/handbook/engineering/ux/technical-writing/workflow/#for-a-product-change)以外的任何其他原因.
*   解决现有文档中的空白，或对现有文档进行改进.
*   处理与文档相关的特殊项目.

## How to update the docs[](#how-to-update-the-docs "Permalink")

要更新 GitLab 文档：

1.  Either:
    *   单击[https://docs.gitlab.com](https://s0docs0gitlab0com.icopy.site)上任何页面底部的" **编辑此页面"**链接.
    *   导航到[GitLab 文档指南](index.html)页面上列出的存储库和文档路径之一.
2.  请遵循页面上列出的描述的标准和过程，包括：
    *   [结构和模板](structure.html)页面.
    *   [样式指南](styleguide.html) .
    *   [降价指南](https://about.gitlab.com/handbook/markdown-guide/) .
3.  遵循 GitLab 的[合并请求准则](../contributing/merge_request_workflow.html#merge-request-guidelines) .

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

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

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

要寻求帮助：

1.  找到相关[DevOps 阶段组](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments)的技术作家.
2.  Either:
    *   如果需要紧急帮助，请直接在问题或合并请求中分配技术作家.
    *   如果需要非紧急帮助，请在问题或合并请求中 ping 技术作家.

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

### Reviewing and merging[](#reviewing-and-merging "Permalink")

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

*   清晰易懂，易于目标受众浏览和理解.
*   符合[文档指南](index.html)和[样式指南](styleguide.html) .

如果作者或审稿人有任何疑问，他们可以提及被分配到相关[DevOps 阶段小组的作者](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments) .

该过程涉及以下内容：

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

该过程反映在" **文档** [合并请求"模板中](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/merge_request_templates/Documentation.md) .

## Other ways to help[](#other-ways-to-help "Permalink")

如果您有更多文档资源的想法，请使用"文档"模板[创建问题](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Documentation) .

## Post-merge reviews[](#post-merge-reviews "Permalink")

如果在合并之前未分配给技术作家进行审核，则开发人员或维护人员必须在合并后立即安排审核. 为此，请使用" [文档审阅"描述模板](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Doc Review)创建一个问题，并从引入了文档更改的合并合并请求中链接到该问题.

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

*   里程碑发布还有很短的时间. 如果还有不到三天的时间，请寻求合并后的审查，并通过 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 的定义的](../contributing/merge_request_workflow.html#definition-of-done)一部分.
*   当代码在里程碑发布之前完成得很好并且需要更大的文档更改时，这种合并前的 Technical Writer 审核应该是最常见的.
*   如果重要的是尽快使它附带的代码合并，那么可以要求对文档进行合并后技术审查. 在这种情况下，原始 MR 的作者将在后续 MR 中阐述技术作家提供的反馈.
*   技术作家还可以帮助您确定无需技术作家审查就可以合并文档，而审查将在合并后立即进行.

### Before merging[](#before-merging "Permalink")

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

*   该[产品徽章](styleguide.html#product-badges)已应用.
*   包含引入该功能的 GitLab [版本](styleguide.html#text-for-documentation-requiring-version-text)已包括在内.
*   标题的更改不会影响应用内超链接.
*   记录了特定的[用户权限](../../user/permissions.html) .
*   为了发现，这些新文档从更高级别的索引链接在一起.
*   遵循样式指南：
    *   用于[目录和文件](styleguide.html#work-with-directories-and-files) .
    *   对于[图像](styleguide.html#images) .

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