编写可被搜索到的文档

编写良好文档的关键之一是使其可被搜索到。读者会结合使用内部站点搜索和外部搜索引擎（如 Google 或 duckduckgo）。

为了确保 Ansible 文档可被搜索到，您应该

  1. 使用清晰反映您正在记录的内容的标题。

  2. 尽可能对过程或高级步骤使用编号列表。

  3. 尽量避免链接到 GitHub blobs。

在文档中使用清晰的标题

当我们想找到某些东西时，我们都会使用简单的英语。例如，此页面的标题可以是以下任何一个：

  • 搜索优化

  • 可搜索的文档

  • 为可搜索性而编写

我们真正想要描述的是 - 如何编写文档才能让搜索引擎找到我的内容？这个简单的短语驱动了本节的标题。当您为文档创建标题时，请花一些时间思考您会在搜索框中输入什么来找到它，或者更重要的是，不太熟悉 Ansible 的人会如何尝试找到该信息。您的标题应该回答这个问题。

请注意一点 - 您确实想限制标题的大小。像 我如何编写文档才能让搜索引擎找到我的内容？ 这样的完整标题太长了。搜索引擎会截断超过 50-60 个字符的任何内容。长标题也会在智能手机等较小的设备上换行。

为 零位置 代码片段使用编号列表

Google 可以通过在搜索结果顶部添加 特色代码片段来优化搜索结果。此代码片段在第一个搜索结果中提供了一个关于文档的小窗口，它添加了比其他搜索结果更多的详细信息，并且偶尔可以直接回答读者的问题，或者至少验证链接的页面是读者正在寻找的。

Google 以编号步骤的形式返回特色代码片段。在可能的情况下，您应该在文档页面的顶部附近添加编号列表（如果合适）。这些步骤可以是读者将遵循的确切过程，也可以是文档主题的高级介绍，例如本页顶部的编号列表。

GitHub blobs 在搜索结果中的问题

搜索引擎通常不会在搜索结果中返回 GitHub blobs，至少不会在排名较高的位置。虽然从文档链接到 GitHub blobs 是可能的，有时也是必要的，但更好的方法是将该信息复制到 Ansible 文档中的 .rst 页面中。

其他搜索提示

虽然可能无法使您的文档适应所有搜索优化，但在编写文档时请记住以下几点：

  • 搜索引擎不会解析 html 页面中的 `#` 之后的内容。例如，此页面上的所有子标题都会附加到主页 URL。因此，当我搜索“为零位置代码片段使用编号列表”时，搜索结果将是指向此页面顶部的链接，而不是直接指向我搜索的子标题的链接。使用 本地目录 有助于缓解此问题，因为读者可以扫描页面顶部的标题并单击他们正在寻找的部分。对于关键文档，请考虑创建一个新的页面，该页面可以直接作为搜索结果页面。

  • 让您的前几句话清楚地描述您的页面主题。搜索引擎不仅返回 URL，还会返回 URL 上信息的简短描述。对于 Ansible 文档，我们没有嵌入在每个页面上的描述元数据。相反，搜索引擎会返回页面上的前几句话（140 个字符）。这使得您的第一句话或两句话对于正在 Ansible 中搜索内容的读者非常重要。