提高 Swift-DocC 内容的可发现性

♪ 柔和乐器演奏的嘻哈音乐 ♪ ♪ 大家好 我叫 Bea 是文档组的 交互设计师 我将分享如何提高 您的 Swift-DocC 内容的可发现性 在本次讲座中 我将介绍 网页端 Swift-DocC 文档 新的导航体验 并分享如何优化内容 以便快速查找的小技巧 如果您想在示例中详细 了解何为 Swift-DocC 以及如何用来为您的框架和 App 制作出色的编程文档 请查看这些 WWDC 讲座

现在让我们来看看全新的网页端 Swift-DocC 文档导航器 今年 当您发布文档站点时 您将获得全新的导航体验 它将使您的内容得到最好的呈现 该页面主要包含两个部分 左侧是导航器（Navigator） 和筛选器栏（Filter Bar） 您可以通过他们浏览文档 并快速找到相应的 API 右侧是内容视图（Content View） 经过优化 它可以灵活适配 不同尺寸的屏幕和导航器 由于导航器与内容视图是分开的 所以可以很轻松地 在不同页面之间快速切换 您还可以使用 披露指示器（Disclosure Indicator） 在结构树中深入探索 学习 API 的层次结构 这些功能大大易化了 文档浏览 另一方面 如果您知道要查找内容 并想尽快查到出处 您可以使用导航器中的筛选器栏 进行过滤筛选 让我们看看筛选器的使用效果 假设您正在查找 Habitat 当您点击筛选器栏并输入时 您就能筛选出 含有这个关键词的相关导航 您可以清除筛选器以重置导航栏 还可以通过筛选来查看文章 教程 甚至可以通过选择标签 来隐藏已弃用的页面 例如 如果您选择 教程（Tutorials）标签 查找 Meet SlothCreator 教程 就会非常方便 现在您已了解了导航器的相关更新 我将继续谈谈 如何充分利用这一新功能 这里有一些关于 如何优化内容的提示和技巧 可以帮助开发者尽可能顺利地 找到他们正在查找的页面 我现在来展示如何优化文档框架 例如 SlothCreator 您可以使用 SlothCreator 来给您在自然界中 发现的树懒分类 并创造新的可爱的虚拟树懒 我刚刚完成了框架文档编写 还没有编写任何 markdown 页面 我会从使用 Swift-DocC 的自动组织功能开始 这意味着我的导航器是按类型组织的 比如教程 文章 协议和结构 这已经是一个很好的开始 但是我可以通过我的文档 更好地指导开发者 为了优化内容 我将遵循以下三步

首先 定义我可以用这个框架做的 的主要高阶主题 然后 我将按重要性和特异性 来组织我的页面 最后 我将优化我的组标题 以确保它们尽可能清晰明了且有用 我觉得这个过程就像创建一个地图 它帮助人们理解边界 和地区的一般特征 并弄清楚如何从一个地方 到另一个地方 同样 文档导航器可以帮助开发者 了解使用一组 API 可以做什么 以及如何导航到他们正在查找的页面 我将通过定义 SlothCreator 的主要高级主题 来帮助开发者理解 他们可以用我的 API 做什么 这些主题将会在 SlothCreator 页面上的导航器中显示 就在我文档的顶层页面 这将是开发者在登录文档网站时 最先看到的内容之一 这让我可以留下良好的第一印象 也可以帮助开发者更好地理解 这个框架的作用 现在 让我想想我的第一个主题 SlothCreator 的主要功能之一 就是创造树懒 他们有名字 有颜色 甚至有特殊的力量 总而言之 我将命名这个主题组为 Sloth Creation 稍后 我将决定该组中包含哪些页面 所以现在我先只留下一个占位符 创建树懒后 您可以通过 许多不同的方式将其可视化 例如在 App 屏幕上 在地图视图中 我将其命名为 Sloth Views 当然 管理树懒的工作量很大 他们需要被喂养 娱乐 照顾 我将其命名为 管理（Management） 在这三组中您已经可以 实现很多功能了 站在一个从未使用过 SlothCreator 的开发者角度 我希望有一个简单的方法 来了解如何开始使用这个框架 考虑到这一点 我将创建一个具有 高级别介绍性内容的主题组 我将其命名为 基本信息（Essentials） 太棒了 尽管您可以用 SlothCreator 做很多事情 但我 只强调了四个最重要且全面的主题组 通过减少可用选项的数量 我增加了开发者成功查看 下一步操作的机会 并没有特别规定 我应该创建的主题组数量 但我通常尽量保持 每页不超过 10 个 回到地图的那个想法 我想为开发者提供分步指南 告诉他们每一步该怎么做 组顺序对于创造出色体验至关重要 再来看看我的主题组 它们大部分都井井有条 首先 您必须创建一个树懒 然后您可以将其可视化 接着就可以管理它 我现在唯一要做的更改是 将 Essentials 移至列表的开头 以便开发者最先看到初学者内容 现在 是时候决定页面和主题了 这些应该在每个类别下进行组织 让我从 Essentials 开始 它将位于导航器的最顶部 并可能是开发者最先看到的东西之一 所以我想确保这个功能 包含了最重要的介绍性内容 这是一个极佳位置来突出显示 介绍性文章和教程 这样可以确保开发者 快速找到分步代码示例 就我个人而言 这也是我最喜欢的学习方式 考虑到这些因素 我决定在 Essentials 下组织三个小组 Meet SlothCreator 教程 Getting Started with Sloths 文章 和树懒结构 这是我框架中的核心 API 之一 我将对其他三个组 重复相同的操作流程 这让我感觉很友好因为我最先看到了 最重要和最广泛的主题 当我在树中深入探索时 组变得更加具体和高级 例如 在 Essentials 中 我会找到 获取可视化属性（Getting Visual Attributes） 在 Getting Visual Attributes 属性中 我会找到 获取标准色（Getting the Standard Colors） 太好了 我的文档以这种方式组织 引导开发者顺利浏览内容 接下来 我想确保主题组的标题 同样也有高质量 一个优秀的主题组标题的首要特征 就是清晰明了 描述清楚 一个好的标题本身就能让人很好理解 它不需要太多额外解释 回到我的主题标题 它们还有提高的空间 我写的最后一个主题标题是 Management 这组 API 都是关于 您可以做什么 来管理您的树懒：活动（Activity）、 照顾时间表（CareSchedule） 食物生成器（FoodGenerator） 和树懒的食物（Sloth.Food） 乍一看 这似乎是个不错的标题 然而 经过进一步考虑 Management 是一个如此广泛的术语 它包含的意思太过宽泛 所以用作标题并不理想 为了使该标题更清晰和更具描述性 我将把其命名为 照顾和喂养（Care and Feeding） 现在 我理解这个组是关于 照顾我的树懒并给它们食物 由于这个原因 主题组标题的排他性也很重要 如果我的标题是可以彼此替换的 就很难知道哪一个包含我要找的东西 例如 获取超能力（Fueling Superpowers） 获得神奇能力（Getting Magical Abilities） 和施展魔法（Casting Enchantments） 是非常相似的主题 并可能被组织在同个标题下 通过保持标题尽可能排他性 开发者更容易找到 下一步的方向 我在组织和页面标题上做的工作越多 开发者就越有可能顺利地 找到他们想要的页面 而且 我非常鼓励偶然性 换句话说 快乐的意外发现 通过将精心设置的主题组织在一起 开发者能够找到相关的页面 例如 当我学习 SlothCreator 基本信息时 我很高兴在列表中找到 获得神奇能力（Getting Magical Abilities） 所有这些提示和技巧 真的让我的文档更上一层楼 跟以前相比好多了！ 现在 让我们回顾一下如何提高您的 内容可发现性并使其易于开发者使用 首先 确定文档的主要主题 然后按重要性和特异性组织您的内容 接着 通过将相关主题组织在一起 来鼓励开发者浏览发现 最后 为您的页面和组编写 清晰且具有排他性的标题 感谢您抽出宝贵时间 来学习如何优化您的文档 我相信开发者会非常受用 祝您有个愉快的 WWDC 体验！ ♪