文档的文件夹结构

文档按顶级受众文件夹进行分类，包括 user、 administration 和 development（贡献）文件夹。

除此之外，我们主要遵循 GitLab 用户界面或 API 的结构。

我们的目标是建立一个清晰的层级结构，使用有意义的 URL，如 docs.gitlab.com/user/project/merge_requests/。通过这种模式，您可以立即知道您正在浏览的是关于项目功能的用户相关文档；特别是关于合并请求的文档。我们网站的路径与我们的仓库路径相匹配，因此清晰的结构也使文档更新更加容易。

将特定产品区域的文件放入相关文件夹：

以下是遗留或已弃用的文件夹。 不要向这些文件夹添加新内容：

• /gitlab-basics/
• /topics/
• /university/

处理目录和文件

处理目录和文件时：

1. 创建新目录时，总是以 _index.md 文件开始。 不要使用其他文件名，也不要创建 README.md 文件。
2. 在文件名、目录名、分支名以及任何生成路径的名称中，不要使用特殊字符、空格或大写字母。
3. 创建或重命名文件或目录时，如果名称包含多个单词，请使用下划线 (_) 而不是空格或连字符。例如，正确的命名方式是 import_project/import_from_github.md。这适用于 图片文件 和 Markdown 文件。
4. 不要将视频文件上传到产品仓库。 请改为 链接或嵌入视频。
5. 在 doc/user/ 目录中：
   • doc/user/project/ 应包含所有项目相关文档。
   • doc/user/group/ 应包含所有群组相关文档。
   • doc/user/profile/ 应包含所有个人资料相关文档。 在 /profile 下导航的每个页面都应有自己的文档，例如 account.md、applications.md 或 emails.md。
6. 在 doc/administration/ 目录中：所有与管理员相关的文档，包括在 UI 和后端服务器上执行的管理员任务。

如果您不确定放置文档或内容添加的位置，这不应阻止您编写和贡献内容。请使用您的最佳判断，然后询问您的 MR 审查者以确认您的决定。您也可以在过程中的任何阶段询问技术作者。技术写作团队会审查所有文档更改，如果有更好的位置，他们可以移动内容。

尽可能避免重复

尽可能不要在多个地方包含相同的信息。 而是链接到单一的真实来源。

例如，如果您在 主仓库 之外的仓库中有代码，并且在同一仓库中有文档，您可以将文档保留在该仓库中。

然后您可以：

• 将其发布到 https://docs.gitlab.com。
• 通过在全局导航中添加条目，从 https://docs.gitlab.com 链接到它。

跨文档引用

• 为每个文件夹提供一个 _index.md 页面，介绍该主题，并介绍和链接到子页面，包括任何下一级子路径的索引页面。
• 为了确保可发现性，确保每个新的或重命名的文档都从其更高级别的索引页面和其他相关页面链接。
• 引用其他 GitLab 产品和功能时，链接到它们各自的文档，至少在首次提及时要这样做。
• 引用第三方产品或技术时，链接到它们的外部网站、文档和资源。