# 组织内容

> 围绕读者目标与内容类型组织文档。

---

LLMS index: [llms.txt](/llms.txt)

---

Oink 根据 Hugo 内容树生成文档侧栏，因此目录结构也是读者体验的一部分，而不只是源码组织细节。先明确读者需要解决的问题，再建立能够快速找到答案的最小层级。

## 从读者目标出发 {#start-from-reader-goals}

为新读者提供一条从产品背景到首次成功操作的短路径；为回访读者提供直达操作指南、参考资料与故障排查的入口。一套实用文档通常需要：

- 说明范围与产品边界的概览；
- 能得到可运行结果的快速上手路径；
- 围绕常见工作的任务指南；
- 参数、API 与兼容性的参考页面；
- 覆盖常见故障的诊断与恢复说明。

当示例能够直接复制或对比时，它们很有价值，但不应取代解释行为的操作步骤与参考资料。

## 使用可预测的内容类型 {#use-predictable-content-types}

每个页面只聚焦一种读者意图：

| 内容类型 | 读者的问题                   |
| -------- | ---------------------------- |
| 概览     | 这是什么，什么时候应该使用？ |
| 教程     | 怎样得到第一个可运行结果？   |
| 操作指南 | 怎样完成一项具体任务？       |
| 参考     | 有哪些字段、命令或接口？     |
| 解释     | 系统为什么采用这种行为？     |
| 故障排查 | 怎样诊断故障并恢复？         |

不要为了复刻组织架构而建立空的一级目录。只有当多篇页面共享稳定的读者目标时，才增加新的分区。

## 保持浅层结构 {#keep-the-hierarchy-shallow}

优先使用简短明确的 URL，不要建立过深的分类树。通过页面权重安排学习顺序，并让同一分区的权重保持一致间隔，便于插入新页面。每个可导航页面都应提供图标与精简描述，让侧栏和分区索引便于扫描。

Hugo 页面包与分区模型详见[添加内容](/zh/docs/content/adding-content/#organizing-your-documentation)，侧栏行为详见[导航与菜单](/zh/docs/content/navigation/)。

## 同步规划多语言内容 {#plan-languages-together}

在同一目录中同时创建英文源页面与简体中文译文。页面顺序、读者意图、示例与稳定标题 ID 应保持一致。两种语言的篇幅不必相同，但必须传达等价信息。

## 检查完整访问路径 {#review-the-complete-route}

移动或新增页面后，检查文档首页、分区索引、侧栏、面包屑、前后页导航、本地搜索与全部首页链接。发布前应构建两种语言，并验证渲染后的片段链接。