Help us learn about your current experience with the documentation. Take the survey.

任务主题类型

任务提供完成某个流程的说明。

格式

任务应采用以下格式：

title: 标题（以主动动词开头，如"创建小部件"或"删除小部件"）
---

当你想要...时执行此任务。

先决条件（可选）：

- 事项 1
- 事项 2
- 事项 3

执行此任务：

1. 位置然后操作。（转到此菜单，然后选择此项目。）
1. 另一步骤。
1. 另一步骤。

任务结果（可选）。后续步骤（可选）。

这是一个示例。

title: 创建 issue
---

当你想要跟踪 bug 或未来工作时创建 issue。

先决条件：

- 你必须拥有项目的至少 Developer 角色。

创建 issue：

1. 在左侧边栏，选择 **Search or go to** 并找到你的项目。
1. 选择 **Plan** > **Issues**。
1. 在右上角，选择 **New issue**。
1. 完成字段。（如果你有列出每个字段的参考内容，在此处链接到它。）
1. 选择 **Create issue**。

Issue 已创建。你可以通过转到 **Plan** > **Issues** 来查看它。

任务主题标题

对于标题文本，使用 主动动词 + 名词 的结构。 例如，创建 issue。

如果页面上的多个任务共享先决条件，你可以创建一个单独的主题，标题为 Prerequisites。

当任务只有一个步骤时

如果你需要编写只有一个步骤的任务，将该步骤设置为无序列表项。 这种格式有助于突出显示该步骤，同时保持与列表规则的一致性。

例如：

title: 创建 merge request
---

创建 merge request：

- 在右上角，选择 **New merge request**。

当存在多种执行任务的方式时

如果 UI 中存在多种执行任务的方式，你应该只记录主要方式。

但是，有时你必须记录多种执行任务的方式。当这种情况发生时：

  • 像往常一样介绍任务。然后，对于每种执行任务的方式，添加一个主题标题。
  • 将主题标题嵌套在任务主题标题下一级。
  • 按降序列出任务，最可能的方法在前。
  • 尽可能使任务标题简洁。在可能的情况下， 使用 不定式 + 名词。

这是一个示例。

title: 更改默认分支名称
---

你可以为实例或组更改默认分支名称。
如果名称是为实例设置的，你可以为组覆盖它。

## 对于实例

先决条件：

- 你必须拥有实例的至少 Maintainer 角色。

为实例更改默认分支名称：

1. 步骤。
1. 步骤。

## 对于组

先决条件：

- 你必须拥有组的至少 Developer 角色。

为组更改默认分支名称：

1. 步骤。
1. 步骤。

在 UI 和 API 中执行任务

通常存在一个 API 来执行你在 UI 中执行的任务。当这种情况发生时：

  • 不要为单句 API 链接使用单独的标题。

  • 不要在 Use GitLab 文档中包含 API 示例。API 示例 属于 API 文档。如果你有 GraphQL 示例，将它们放在 自己的页面上，因为 API 文档可能会在将来移动。

  • 如果不需要，不要提及 API。用户可以搜索 API 文档，额外的链接会增加混乱。

  • 如果有人强烈要求你提及 API，在 UI 任务末尾 添加这句话：

    创建 issue，你也可以 [使用 API](link.md)。

任务介绍

开始任务主题时，使用 主动动词 + 名词 的结构，并 提供关于操作的上下文。 例如，当你想要跟踪 bug 或未来工作时创建 issue。

开始任务步骤时，使用简洁的动作后跟冒号。 例如，创建 issue：

任务先决条件

作为最佳实践，如果任务要求用户拥有 Guest 以外的角色， 将最低角色放在先决条件中。有关如何编写每个角色的短语， 请参阅 词汇表。

Prerequisites 必须始终是复数，即使列表中只有一项。

相关主题