编写可搜索的文档

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

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

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

当我们想找东西时，我们都使用简单的英语。例如，本页的标题可以是以下任何一个

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

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

Google 可以通过在搜索结果顶部添加精选片段来优化搜索结果。此片段提供了对第一个搜索结果中文档的小窗口，比其他搜索结果提供了更多详细信息，有时甚至可以当场回答读者的问题，或者至少验证链接页面是否是读者正在寻找的内容。

Google 以编号步骤的形式返回精选片段。在适当的情况下，您应该在文档页面的顶部添加一个编号列表。这些步骤可以是读者会执行的确切过程，也可以是文档主题的高级介绍，例如本页顶部的编号列表。

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

虽然可能无法根据所有搜索优化调整您的文档，但在编写文档时请牢记以下几点

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