# 组织内容

> 关于如何组织文档站点的可选指导和建议。

---

LLMS index: [llms.txt](/oink.pgsty.com/llms.txt)

---

查看我们的[示例站点](https://example.docsy.dev/about/)，你会发现其中的“文档”分区被划分为多个子分区；每个子分区都附有建议，说明适合放入哪些内容。

## 必须采用这种结构吗？ {#do-i-need-to-use-this-structure}

当然不必！示例站点的结构面向功能众多、潜在任务复杂、参考资料丰富的大型产品和大型文档集。对于更简单的文档集（比如本站），围绕用户需要了解的具体功能来组织文档就很好。即使面对大型文档集，你也可能发现这套结构不能直接照搬，或者没有必要用到其中的全部分区类型。

不过，我们建议至少提供以下内容（本站也是如此）：

- 产品的
  **概览**——可以放在文档首页，也可以单独成页，用来告诉用户为什么值得关注你的项目；
- **开始使用** 页面；
- 一些 **示例**。

你也可以围绕项目功能编写任务指南或操作方法。如果更喜欢本站这种精简结构，可以复制整个 Docsy 用户指南站点，也可以只复制其中的文档分区。

> [!TIP]
>
> 如果想复制本指南，请注意它的[源文件](https://github.com/google/docsy/tree/main/docsy.dev)位于 Docsy 主题仓库
> **内部**，因此没有自己的 `themes/` 目录；我们通过运行
> `hugo server --themesDir ../..`
> 使用父目录中的 Docsy。你可以复制站点并[添加包含 Docsy 的 `themes/` 目录](/zh/docs/get-started/other-options/#option-2-clone-the-docsy-theme)，也可以只把
> `docs/` 文件夹复制到现有站点的内容根目录。

进一步了解 Hugo 和 Docsy 如何利用文件夹及其他文件[组织站点](/zh/docs/content/adding-content/#organizing-your-documentation)。

## 为什么采用这种结构？ {#why-this-structure}

示例站点的结构来自我们为不同类型项目创建和使用大型文档集的经验，也参考了针对一些大型站点开展的用户研究。研究表明，用户最关心并会立即寻找的是“开始”或“开始使用”分区——顾名思义，他们希望马上动手；其次是可供探索和复制的示例。因此，我们把这两类内容设计成站点中醒目的顶层文档分区。

用户还希望找到易于检索的“配方”，以便完成具体任务，并把这些配方组合成自己的应用或项目。因此，我们建议把这类内容组织为“任务”。概念说明、参考文档和端到端教程等其他内容类型并非对所有文档集都同样重要，对小型项目尤其如此。示例站点也明确说明这些分区均为可选项。

随着我们进一步了解用户如何使用技术文档，尤其是开源项目文档，我们还会继续完善示例站点的结构。

## 写作风格指南 {#writing-style-guide}

本指南和示例站点只介绍如何把文档内容组织成页面和分区。至于每个页面应如何组织和撰写内容，我们推荐参考
[Google 开发者文档风格指南](https://developers.google.com/style/)，尤其是其中的[风格指南要点](https://developers.google.com/style/highlights)。