故障排查主题类型

故障排查主题应该放在页面的最后。

如果一个页面有五个或更多故障排查主题，将这些主题放在单独的页面。

包含哪些类型的故障排查信息

故障排查信息包括：

• 可能被视为有风险的问题解决信息。
• 关于罕见情况的信息。所有故障排查信息 都会包含在内，无论用户遇到这种情况的可能性有多小。

这类内容对他人有帮助，收益大于风险。 如果你认为有例外情况，请联系技术写作团队。

GitLab Support 维护自己的故障排查内容。

格式

故障排查可以是三种类型之一：介绍型、任务型或参考型。

介绍型主题

这个主题介绍页面的故障排查部分。 例如：

## 故障排查

使用 <x 功能> 时，你可能会遇到以下问题。

故障排查任务

标题应与标准任务类似。 例如，“运行调试工具"或"验证语法”。

故障排查参考

这个主题包含消息。为了保持一致性，对临时解决方案使用 workaround，对永久解决方案使用 resolution 和 resolve。例如：

### 消息或其描述

你可能会收到一个错误消息，显示 <错误消息>。

当...时会出现此问题。

临时解决方案是...

如果存在多个原因或解决方案，考虑将它们放入表格格式。 如果你使用确切的错误消息，用反引号包围，使其显示为代码。

有关解决方案类型的更多指导，请参见 workaround 和 resolution, resolve。

故障排查主题标题

故障排查参考主题的标题：

• 考虑至少包含部分输出消息。 如果消息超过 70 个字符，包含最重要的文本，或者描述该消息。
• 在标题开头说明消息类型。这表示严重程度。例如，Error:、Warning:。
• 不要在标题中使用链接。

如果不在标题中放入完整消息，请在正文中包含它。例如：

## Error: `unexpected disconnect while reading sideband packet`

不稳定的网络条件可能导致 Gitaly 在尝试从主站点获取大型仓库数据时失败。这些情况可能导致此错误：

```plaintext
curl 18 transfer closed with outstanding read data remaining & fetch-pack:
unexpected disconnect while reading sideband packet
```

要解决此问题...

Rails 控制台写入函数

如果故障排查建议包含更改 GitLab 实例数据的函数， 添加以下警告：

{{< alert type="warning" >}}

更改数据的命令如果运行不正确或在不当条件下运行，可能会造成损害。始终先在测试环境中运行命令，并准备好备份实例以便恢复。

{{< /alert >}}

故障排查页面类型

当一个页面有五个或更多故障排查主题时，创建一个单独的故障排查页面。

遵循以下约定：

• 将页面命名为 Troubleshooting <feature>。
• 在左侧导航中，仅使用 Troubleshooting 一词。
• 在导航文件中，将新页面嵌套在其所属功能下。
• 将文件命名为 <feature>_troubleshooting.md。