编写文档以便搜索可以找到它

编写优秀文档的关键之一是使其可查找。读者使用内部站点搜索和外部搜索引擎（如 Google 或 duckduckgo）的组合。

为了确保 Ansible 文档可查找，您应该

在文档中使用清晰的标题

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

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

一个警告 - 您确实希望限制标题的大小。诸如如何编写文档以便搜索引擎可以找到我的内容？之类的完整标题太长了。搜索引擎会截断任何超过 50 - 60 个字符的内容。长标题也会在智能手机等小型设备上换行。

Google 可以通过在搜索结果顶部添加精选摘要来优化搜索结果。此摘要提供了一个小窗口，展示了第一个搜索结果的文档，该文档提供了比其余搜索结果更多的详细信息，并且有时可以在那里回答读者的疑问，或者至少验证链接的页面是读者正在寻找的内容。

Google 以编号步骤的形式返回精选摘要。在可能的情况下，您应该在文档页面的顶部附近添加编号列表（如果适用）。这些步骤可以是读者将遵循的确切过程，也可以是对文档主题的高级介绍，例如此页面顶部的编号列表。

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

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

搜索引擎不会解析 HTML 页面中的 `#` 之后的内容。因此，例如，此页面上的所有子标题都附加到主页面 URL。因此，当我搜索“为零位置代码段使用编号列表”时，搜索结果将是指向此页面顶部的链接，而不是直接指向我搜索的子标题的链接。使用本地 TOC有助于缓解此问题，因为读者可以扫描页面顶部的标题并单击他们正在寻找的部分。对于关键文档，请考虑创建一个可以直接搜索结果的页面。
使您的前几个句子清楚地描述您的页面主题。搜索引擎不仅返回 URL，还返回 URL 上信息的简短描述。对于 Ansible 文档，我们没有在每个页面上嵌入描述元数据。相反，搜索引擎返回页面上的前几个句子（140 个字符）。这使得您的第一句话或两句话对于正在搜索 Ansible 中某些内容的读者非常重要。