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

文档工作流程

GitLab 的文档遵循一个工作流程。 创建和维护 GitLab 产品文档的过程取决于文档的类型：

当满足以下条件时，文档是必需的：

  • 发布了影响用户或管理员体验的新或增强功能。
  • 用户界面或 API 发生更改。
  • 流程、工作流或先前记录的功能发生更改。
  • 功能被弃用或移除。

当添加或更改后端功能时，通常不需要文档。

管道和分支命名

gitlab 和 gitlab-runner 项目的 CI/CD 管道已配置为 在仅包含文档更改的合并请求上运行更短、更快的管道。

如果您向 omnibus-gitlab、charts/gitlab 或 gitlab-operator 提交仅文档的更改， 要使短管道运行，您必须按照以下指南命名分支：

分支名称 有效示例
以 docs/ 开头 docs/update-api-issues
以 docs- 开头 docs-update-api-issues
以 -docs 结尾 123-update-api-issues-docs

此外，由于某些代码测试使用这些文件作为示例，gitlab 项目中这些文件的更改会自动触发长管道：

  • doc/_index.md
  • doc/api/settings.md

当您编辑这些页面时，长管道的出现与代码 MR 中相同，但您不需要任何额外的批准。如果合并时 pre-merge-checks 作业失败并显示 Expected latest pipeline (link) to be a tier-3 pipeline! 消息，请将 ~"pipeline::tier-3" 标签添加到 MR 并运行新管道。

如果您的合并请求包含任何代码更改，将为它们运行长管道。

有关长管道的更多信息，请参阅 GitLab 项目的管道。

移动内容

当您将内容移动到新位置，并在同一个合并请求中编辑内容时， 请使用单独的提交。

单独的提交有助于审查者，因为移动内容的 MR 差异 不能清晰地突出显示编辑。 当您使用单独的提交时，审查者可以在第一个提交的差异中验证位置更改， 然后在后续的提交中验证内容更改。

例如，如果您移动页面，同时也更新页面内容：

  1. 在第一个提交中：将内容移动到新位置，并在需要时放置重定向。 如果可以，请在此提交中修复损坏的链接。
  2. 在后续提交中：进行内容更改。如果尚未修复，请修复损坏的链接。
  3. 在合并请求中：在 MR 描述中向审查者解释这些提交。

您可以添加任意数量的提交，但请确保第一个提交只移动内容， 而不编辑内容。

产品变更的文档

任何新功能或更改的功能都需要文档，并且：

  • 作为功能开发的一部分创建或更新，并且几乎总是在 与功能代码相同的合并请求中。将文档包含在 与代码相同的合并请求中消除了代码和文档 不同步的可能性。
  • 作为特定里程碑功能交付的一部分，是 GitLab 完成定义 所必需的。
  • 从发布文章中链接。

开发者职责

开发者是功能或功能增强文档的主要作者。他们负责：

  • 开发功能所需的初始内容。
  • 与产品经理沟通，了解必须交付哪些文档， 以及何时交付。
  • 向其组中的其他开发者请求技术审查。
  • 向技术写手 分配给 DevOps 阶段组 请求文档审查，该组正在交付新功能或功能增强。

如果可能，包含代码的合并请求应包含文档。 更多信息，请参阅 指南。

此 MR 的作者（前端或后端开发者）应编写文档。

社区贡献者可以向 GitLab 团队成员寻求额外帮助。

编写

由于文档是产品的重要组成部分，如果 ~"type::feature" 问题也包含 ~documentation 标签，您必须将新功能或 更新的文档与功能代码一起交付。

技术写手很乐意提供帮助，根据需要和按问题计划。

对于需要文档的功能问题，除非与产品经理和技术写手另有约定，否则请遵循以下流程：

  • 包含任何新文档和编辑的文档，可以在：

    • 引入代码的合并请求中。
    • 大约同时提交的单独合并请求中。

  • 使用产品经理在问题中开发的 文档要求，并根据需要讨论任何 进一步的文档计划或想法。

    如果新或更改的文档需要广泛的协作或 讨论，可以使用单独的、链接的问题进行规划过程。

  • 使用 文档指南， 以及从那里链接的其他资源，包括：

  • 在您的问题或合并请求中，或在 #docs Slack 频道中，联系相关 DevOps 阶段 的技术写手，如果您：

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

  • 如果您在单独的合并请求中处理文档，请确保 文档尽可能与代码合并同时合并。

  • 如果功能具有功能标志，遵循记录功能标志问题的策略。

审查

在合并之前，开发者提交的文档更改必须由以下人员审查：

  • 合并请求的代码审查者。这称为技术审查。
  • 可选地，其他参与工作的人员，如其他开发者或 产品经理。
  • DevOps 阶段组的技术写手，在特殊情况下除外， 可以请求 合并后审查。
  • 项目的维护者。

产品经理职责

产品经理负责功能或功能增强的 文档要求。他们还可以：

  • 与技术写手联系进行讨论和协作。
  • 自己审查文档。

对于需要任何新文档或更新文档的问题，产品经理必须：

  • 添加 ~documentation 标签。
  • 确认或添加文档要求。
  • 确保问题包含：
    • 任何新功能或更新的功能名称。
    • 概述、描述和适用用例（当适用时）（根据 文档文件夹结构 的要求）。

鼓励每个人在问题中起草文档要求。 但是，产品经理将：

  • 当问题被分配给发布里程碑时，审查和更新 文档详细信息。
  • 在启动时，确定文档详细信息。

技术写手职责

技术写手负责：

  • 参与问题讨论并审查即将到来的 里程碑的 MR。
  • 在被要求时审查问题中的文档要求。
  • 在编写和编辑过程中回答问题，提供帮助和建议。
  • 审查所有重要的新文档和更新的文档内容，无论是在 合并前还是合并后。
  • 协助开发者和产品经理交付功能文档。
  • 确保问题和 MR 被正确标记，并且文档内容具有正确的 元数据。

规划

技术写手：

  • 审查其组的 ~"type::feature" 问题，这些问题是下一个里程碑的一部分， 以了解可能编写的内容范围。
  • 推荐该列表中那些没有 ~documentation 标签但应该有的问题的 ~documentation 标签， 或与产品经理确认是否确实需要文档。
  • 对于该列表中的 ~direction 问题，阅读完整问题并审查其 文档要求部分。与产品经理和在该问题上协作的其他人 解决任何建议或问题，以完善或扩展文档要求。
  • 更新技术写作里程碑计划（示例 由 问题模板 创建）。
    • 添加显示即将到来的里程碑计划文档和 UI 文本工作的看板或筛选器的链接。
    • 确认组产品经理或工程经理了解计划的工作。

协作

默认情况下，开发者将独立处理文档更改，但 开发者、产品经理或技术写手可以为任何给定问题提出更广泛的 协作。

此外，技术写手随时可以回答问题。

审查

技术写手在文档更改合并前后提供非阻塞审查。 识别的会阻止或减慢更改发布的问题应在链接的、后续的 MR 中处理。

文档要求

功能文档要求应作为问题的一部分包含在 文档 部分中，用于规划该功能。使用 功能提案 模板 创建的问题默认包含此部分。

任何人都可以添加这些详细信息，但将问题分配给 特定发布里程碑的产品经理将确保这些详细信息在 该里程碑启动时存在并最终确定。

开发者、技术写手和其他人可以根据请求随时帮助进一步完善此计划。

应包括以下详细信息：

  • 文档应指导并使用户能够理解或完成哪些概念和流程？
  • 为此，需要哪些新页面？哪些页面或子部分 需要更新？考虑用户、管理员和 API 文档的更改和添加。
  • 对于任何指南或说明集，它应该帮助解决单个用例， 还是灵活地解决一定范围的用例？
  • 我们是否需要更新先前推荐的工作流？我们应该从各种相关位置 链接新功能吗？考虑文档应受影响的所有方式。
  • 是否应包含任何关键术语或任务描述，以便文档 能在相关搜索中被找到？
  • 如果适用，包括任何页面或子标题的建议标题。
  • 如果适用，列出任何应交叉链接的文档。

将文档与代码一起包含

目前，技术写作团队强烈鼓励将 文档与相关代码放在同一个合并请求中，但这并非严格强制。文档 在功能 MR 之外添加的单独 MR 中仍然很常见。

工程团队可以选择采用工作流程，其中强制要求 文档包含在代码 MR 中，作为其 完成定义 的一部分。 当团队采用此工作流程时，该团队的工程师必须始终将他们的文档包含在 与其功能代码相同的 MR 中。

单独文档 MR 的缺点

将文档分离到其自身 MR 的工作流程有许多缺点。

如果文档在功能之前合并：

  • GitLab.com 用户可能会在功能发布前尝试使用它，导致 支持工单。
  • 如果功能延迟，文档可能无法及时撤回/回滚，并且可能 意外地包含在该版本的 GitLab 自托管版中。

如果文档在功能之后合并：

  • 功能可能包含在 GitLab 自托管版中，但如果文档 MR 错过截止日期， 则没有任何文档。
  • 功能可能出现在 GitLab.com 用户界面中，而没有任何 文档。对此功能感到惊讶的用户将搜索文档但找不到它， 可能导致支持工单。

有两个单独的 MR 意味着：

  • 两个不同的人可能负责合并一个功能，这在 异步工作方式中不可行。功能可能在 技术写手睡觉时合并，导致两次合并之间可能存在长时间的延迟。
  • 如果文档 MR 被分配给与功能代码 MR 相同的维护者， 他们将必须审查和处理两个 MR，而不是只处理一个。

文档质量可能较低，因为：

  • 将文档放在单独的 MR 中意味着更少的人会看到和验证它们， 增加问题被遗漏的可能性。
  • 在分离的工作流程中，工程师可能只在功能 MR 准备好或 几乎准备好时才创建文档 MR。这给技术写手 很少时间来了解功能以进行良好的审查。这也增加了 他们比期望更快审查和合并的压力，导致因匆忙而出错。

始终将文档与代码一起包含的好处

将文档与代码一起包含（并在开发过程的早期进行）有许多好处：

  • 没有与发布相关的时序问题：
    • 如果功能推迟到下一个版本，文档也会推迟。
    • 如果功能刚好包含在版本中，文档也刚好 包含在内。
    • 如果功能早期出现在 GitLab.com，文档将为我们的 早期采用者做好准备。
  • 只有一个人将负责合并功能（代码维护者）。
  • 技术写手将有更多时间了解功能，并能够更好地 在审查应用或 GDK 中验证文档内容。他们还将能够 提供改进用户界面文本或提供额外用例的建议。
  • 文档将获得更高的可见度：
    • 参与合并请求的每个人都可以审查文档。这可能包括 产品经理、具有深厚领域知识的多个工程师、代码审查者和维护者。他们更可能 发现示例、背景或概念的问题，这些可能是技术写手 不知道的。
    • 提高文档的可见性也有副作用，即 改善其他工程师的文档。通过审查彼此的 MR， 每个工程师自己的文档技能都会提高。
  • 早期考虑文档可以帮助工程师生成更好的 示例，因为他们需要思考用户想要什么示例， 并且需要确保他们编写的代码正确实现该示例。

将文档与代码一起作为工作流程

要将文档与代码一起包含作为强制工作流程，团队当前的 工作流程可能需要一些更改：

  • 工程师必须努力在开发过程的早期包含文档， 以留出充足的时间进行审查，不仅来自技术写手，还有 代码审查者和维护者。
  • 审查者和维护者也必须在代码审查期间审查文档， 以确保描述的流程与功能的预期使用方式匹配， 并且示例正确。 他们不需要担心样式或语法。
  • 技术写手必须直接分配为 MR 的审查者，而不仅仅是被提及。 这可以在任何时间完成，但必须在代码维护者审查之前。 通常文档和代码审查同时进行，作者、审查者和技术写手 一起讨论文档。
  • 当文档准备好时，技术写手将点击批准， 通常不再参与 MR。如果功能在代码审查期间发生更改， 并且文档已更新，技术写手必须重新分配 MR 以验证更新。
  • 维护者可以在文档按原样的情况下合并功能， 即使技术写手尚未给予最终批准。 文档审查不应成为障碍。因此，尽早将文档包含并 分配给技术写手很重要。如果功能在最终文档批准前合并， 维护者必须创建一个 合并后跟进问题， 并将其分配给工程师和技术写手。

您可以将代码和文档审查的并行工作流程可视化如下：

graph TD
  A("功能 MR 创建 (工程师)") --> |分配| B("代码审查 (审查者)")
  B --> |"批准 / 重新分配"| C("代码审查 (维护者)")
  C --> |批准| F("合并 (维护者)")
  A --> D("文档添加 (工程师)"
  D --> |分配| E("文档审查 (技术写手)"
  E --> |批准| F

对于跨多个合并请求的复杂功能：

  • 如果合并请求正在实现未来功能的组件，但组件 尚未对用户可见，则不应包含任何文档。
  • 如果合并请求将以任何方式向用户展示功能，例如启用的 用户界面元素、API 端点或任何类似内容，则该 MR必须有文档。 这可能意味着在实现单个大型功能的过程中，可能会发生多次 文档添加，例如 API 文档和功能使用文档。
  • 如果不清楚哪个工程师应将功能文档添加到他们的 MR 中， 工程经理应在规划期间决定，并将文档与功能发布前必须合并的 最后一个 MR 相关联。这通常是，但不总是，前端 MR。

UI 文本

规划和编写

产品设计师在计划添加或更改 UI 文本时， 应咨询其阶段组的技术写手。

技术写手可以提供任何想法、计划或实际文本的初步审查。 当提供文本的上下文和目标时，可以要求技术写手起草文本。 上下文可能包括文本出现的位置和要传达的信息，这通常回答 以下一个或多个问题：

  • 这有什么作用？
  • 我如何使用它？
  • 我为什么应该关心？

考虑在审查请求中标记技术写手一次，并附上消息说明需要审查的位置。 这将有助于管理每个审查周期的通知量。

MR 审查

创建合并请求后，UI 中所有文本的更改和添加必须由 技术写手审查。 这些可能包括标签（按钮、菜单、列标题和 UI 部分）或任何 将在 UI 中显示的短语，例如微文案或错误消息。

有关编写和审查 UI 文本的更多信息， 请参阅 Copy That: Helping your Users Succeed with Effective Product Copy。

发布文章

每个阶段组的技术写手审查其组中 功能块 （发布文章项目）的产品经理编写的文档。

对于每个发布，还会分配一个技术写手作为 技术写作负责人， 以执行 结构检查 和其他职责。

月度文档发布

当发布新 GitLab 版本时，技术写作团队会发布 版本特定的已发布文档。

文档反馈和改进

要进行与特定代码更改无关的文档更改，技术写作团队鼓励贡献者创建 MR。

如果您从问题而不是 MR 开始，请使用 文档模板。 您应该应用的标签，请参阅 标签。

另外包括：

  • 里程碑：Backlog，直到工作被安排到里程碑。
  • 分配给：None，直到工作被安排到里程碑。 在问题描述或评论中，提及（@username）分配给该组的技术写手以引起注意。
  • 描述：以 Docs: 或 Docs feedback: 开头
  • 任务清单或交付 MVC 的下一步。
  • 可选。如果问题适合社区贡献者：寻求社区贡献 和 快速胜利。

如果问题在技术写手开始工作前需要开发团队的输入，它应遵循阶段和组的问题生命周期。 问题生命周期的示例，请参阅 计划阶段问题。

审查和分类仅文档的积压问题

定期审查和分类您组的文档反馈和改进问题有助于我们将 可用时间 用于改善用户体验的可操作问题上。

先决条件

  • 每个您被分配为技术写手的组的问题分类看板。如果您没有组的问题分类看板，请设置一个名为 Docs only backlog triage - group name 的看板。请参阅 示例看板。
    • 筛选条件应包括 Label=documentation、Label=group::groupname、Label!=type::feature、Label!=type:bug。
    • 在 Edit board 中，确保选中 Show the Open list。
    • 在问题看板上，选择 Create list，并将标签设置为 tw:triaged。

要审查和分类您组的文档反馈和改进问题：

  1. 每月一次，在您组的问题分类看板上，检查 Open 列表中的新问题。
  2. 应用 文档反馈和改进 中描述的标签。
  3. 保持在开放、未分类问题列表中的数量**<10**。
  4. 与组和组产品经理分享已分类的列表。

黑客松

技术写作团队参与 GitLab 黑客松， 有时会举办仅文档的黑客松。

为黑客松创建问题

我们经常为黑客松创建文档问题。这些问题通常基于您对文档运行 Vale 时发现的结果。

  1. 对完整文档集运行 Vale。转到 GitLab 仓库并运行：

    find doc -name '*.md' | sort | xargs vale --minAlertLevel suggestion --output line > ../results.txt

  2. 创建问题。您有几个选项：

    • 使用 脚本 为 Vale 结果中列出的每个 Markdown 文件创建一个问题。 该脚本使用 Doc cleanup 问题模板。
    • 一次创建一个问题，使用 Doc cleanup 问题模板。
    • 使用 Issues API 批量创建问题。

确保分配给问题的标签与 Doc cleanup 问题模板中的标签匹配。

将问题分配给社区贡献者

要将问题分配给社区贡献者：

  1. 移除 Seeking community contributions 标签。
  2. 通过在评论中输入 /assign @username 来分配用户，其中 @username 是贡献者的用户名。
  3. 在评论中提及用户，告诉他们问题现已分配给他们。

尝试限制每个贡献者同时不超过三个问题。一旦他们为已分配的问题之一打开了 MR，您就可以分配另一个问题。

审查黑客松合并请求

当社区贡献者打开黑客松合并请求时：

  1. 查看相关问题。确保 MR 的作者是与要求分配该问题相同的用户。
  • 如果用户未列在问题中，并且另一个用户已请求处理该问题，请不要合并 MR。 要求 MR 作者找到尚未分配的问题，或指向 参与 GitLab 开发。
  1. 努力合并合并请求。
  2. 当您合并时，确保关闭相关问题。

标签

技术写作团队在问题和合并请求上使用以下 标签：

  • 更改类型的标签。最常用的两个标签是：
    • ~"type::feature"
    • ~"type::maintenance" 与 ~"maintenance::refactor
  • 阶段和组标签。例如：
    • ~devops::create
    • ~group::source code
  • ~documentation 专业标签。
  • ~Technical Writing 团队标签。

文档合并请求模板 包含其中一些标签。

可用标签

技术写手处理的所有问题和合并请求必须包含 Technical Writing 标签。

为了进一步分类工作类型，包含以下一个或多个标签：

  • Category:Docs Site：文档网站基础设施或代码。对于与文档本身相关的问题不需要。带有此标签的问题包含在 文档工作流问题看板 中。
  • development guidelines：/developer 目录中的文件。
  • docs-missing：功能文档缺失。文档是特定里程碑功能交付的一部分，作为 GitLab 完成定义 所必需的。将此标签添加到原始功能 MR 或问题中，文档缺失的地方。保留标签用于历史跟踪，并使用 tw::finished 表示文档完成。不适用于 实验功能。
  • documentation：/doc 目录中的文件。
  • global nav：文档站点的左侧导航。在 docs-gitlab-com 项目中使用。
  • L10N-docs：本地化问题、MR 或史诗，影响技术写作团队或 docs.gitlab.com 站点和基础设施的工作流。
  • release post item：发布文章项目。
  • Technical Writing Leadership：由技术写作领导团队驱动或拥有的工作，例如 OKR。
  • tw-lead：由 阶段负责人 之一驱动或需要输入的 MR。
  • tw-style：文档和 UI 文本的样式标准。
  • UI text：任何面向用户的文本，如 UI 文本和错误消息。

其他文档标签包括 vale、docs-only 和 docs-channel。这些标签是可选的。

类型标签

所有问题和合并请求必须分类为三种工作类型之一：bug、功能或维护。 将以下标签之一添加到问题或合并请求中：

  • type::feature
  • type::bug
  • type::maintenance

更多信息，请参阅 工作类型分类。

大多数文档工作使用 type::maintenance 标签。 您还必须应用以下子类型标签之一来进一步分类维护工作的类型：

  • maintenance::refactor：现有文档的编辑和改进。
  • maintenance::workflow：对读者不可见的文档更改，如 linting 和工具更新，以及元数据更改。

例如，如果您打开一个 MR 来重构 CTRT 页面，请应用 type::maintenance 和 maintenance::refactor 标签。 如果您打开一个 MR 来修改元数据，请应用 type::maintenance 和 maintenance::workflow 标签。

工作流标签

写手可以使用 这些标签 来描述他们在问题或合并请求中的工作状态：

  • tw::doing
  • tw::finished

编写内容的技术写手通常添加 tw::doing 标签， 而进行审查的技术写手通常添加 tw::finished 标签。 对于来自社区贡献者的内容提交， 技术写手将在审查过程中添加两个标签。

工作流程如下：

  1. 问题或合并请求被分配给写手进行审查。
  2. 写手在积极工作时添加 tw::doing 标签。
  • 如果写手停止工作超过一周， 他们会移除 tw::doing 标签。
  • 无论何时工作重新开始，写手会再次添加 tw::doing 标签。
  1. 当问题或合并请求上的工作完成时，技术写手（通常是 审查者）添加 tw::finished 标签。
  2. 问题或合并请求被关闭或合并。

tw::finished 标签表示写手已完成他们不关闭或合并的 问题或合并请求。 如果技术写作团队正在关闭或合并，问题或合并请求的 状态会覆盖范围化的 tw 标签状态。技术写手不必使用 tw::finished 标签。

如果技术写手遇到一个带有 tw::finished 标签的开放问题或合并请求， 但需要更多工作，写手应重新添加 tw::doing 范围标签。

合并后审查

如果在合并前未分配给技术写手进行审查，则开发人员或维护者必须立即安排合并后的审查。为此， 请使用 Doc Review 描述模板 创建一个问题，并从引入文档更改的已合并合并请求中链接到它。

可能跳过常规合并前技术写手审查的情况包括：

  • 距离里程碑发布时间很短。如果剩余时间少于三天， 请寻求合并后审查并通过 Slack 提醒写手，以确保尽快完成审查。
  • 更改规模较小，并且您有高度信心 早期功能用户（例如 GitLab.com 用户）可以轻松 按照编写的文档使用。

请记住：

  • 在 GitLab，我们将文档视为代码。与代码一样，文档必须经过审查以确保质量。
  • 文档构成 GitLab 完成定义 的一部分。
  • 合并前技术写手审查应在代码完成早于里程碑发布且文档更改较大时最常见。
  • 如果尽快将文档随附的代码合并很重要，您可以请求合并后技术写手审查。在这种情况下， 原始 MR 的作者可以在后续 MR 中解决技术写手提供的反馈。
  • 技术写手也可以帮助决定文档可以在没有技术写手审查的情况下合并，审查将在合并后很快进行。

无技术写手审查的页面

/doc/solutions 下的文档由解决方案架构师团队创建、维护、 文案编辑和合并。

相关主题