编写易于搜索的文档

编写优质文档的关键之一是使其易于查找。读者会结合使用内部网站搜索和外部搜索引擎，例如 Google 或 duckduckgo。

为确保 Ansible 文档易于查找，您应该

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

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

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

需要注意的一点是 - 您需要限制标题的大小。一个完整的标题，例如“如何编写文档以使搜索引擎能够找到我的内容？”太长了。搜索引擎会截断超过 50-60 个字符的内容。长标题在智能手机等小型设备上也会换行。

Google 可以通过在搜索结果顶部添加精选摘要功能来优化搜索结果。此摘要提供了对第一个搜索结果中文档的简要概述，比其他搜索结果提供了更多详细信息，并且有时可以直接回答读者的问题，或者至少验证链接的页面是否符合读者的要求。

Google 以编号步骤的形式返回精选摘要。在可能的情况下，您应该在文档页面顶部添加一个编号列表（如果合适）。这些步骤可以是读者将要执行的准确步骤，也可以是文档主题的高级介绍，例如本页顶部列出的编号列表。

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

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

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