Improve the discoverability of your Swift-DocC content
System & Services 进阶 20m

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

Improve the discoverability of your Swift-DocC content

2022年6月6日

在 Apple 官方观看视频

一句话判断

Swift-DocC 今年新增了 Web 端导航栏和过滤器——这场 Session 告诉你如何通过合理的目录组织、标签系统和 Curated Topics 让你的文档站更容易被找到和浏览。

这场 Session 讲了什么

Apple 文档团队的交互设计师 Bea 讲解了 Swift-DocC 在 2022 年新增的 Web 导航体验，以及如何优化文档内容以提升可发现性。以一个名为 SlothCreator 的示例框架为案例，展示了从文档组织到导航优化的完整流程。

新增的导航体验包括左侧导航树、过滤器栏、标签筛选等功能。Session 重点讲解了如何利用 Curated Topics、Articles、标签系统等特性让开发者更快找到所需的 API。

值得深挖的点

新增的 Web 导航体验。发布文档站点后，左侧会出现一个导航树（navigator），配合过滤器栏（filter bar）。导航树可以展开查看 API 层级，过滤器支持按名称搜索和按标签（Articles、Tutorials、Deprecated）筛选。导航器与内容视图分离，切换页面无需重新加载。

Curated Topics 的组织方式。Swift-DocC 支持将相关 API 组织到主题页面（Topic Pages）中。合理使用 Topics 可以让导航树更有层次感，开发者能快速理解框架的结构。这是文档可发现性的第一道关卡。

标签（Tags）系统。通过给文档页面打标签，可以让过滤器更精准地工作。标准标签包括 Articles、Tutorials、Deprecated。自定义标签可以按框架特性分类，帮助开发者按关注点筛选内容。

Articles 作为学习入口。Articles 是介于 API 参考和教程之间的内容形式，适合作为某个主题的入门引导。在导航树中，Articles 是最容易被开发者点击浏览的内容，因为它们提供了上下文和概念解释。

代码片段

<!-- 在 Swift-DocC 中组织 Curated Topics -->
# SlothCreator

SlothCreator 是一个用于编目和创建虚拟树懒的框架。

## Topics

### 创建树懒
- ``SlothCreator/Sloth``
- ``SlothCreator/createSloth(name:color:power:)``

### 管理栖息地
- ``SlothCreator/Habitat``
- ``Sloth/HibernateOptions``

### 教程
- <doc:MeetSlothCreator>

<!-- 使用标签增强可发现性 -->
@Metadata {
    @Available(SlothCreator, introduced: "1.0")
    @PageKind(article)
    @PageImage(purpose: icon, source: "sloth-icon")
}

<!-- 组织 Articles 作为学习入口 -->
# 开始使用 SlothCreator

这篇指南将帮助你了解 SlothCreator 的核心概念...

## 概述
树懒是自然界中最迷人的生物之一...

最佳实践

  • 文档目录结构要反映框架的概念层次，不要把所有 API 平铺在一个层级
  • 每个模块至少有一个 Curated Topic 页面作为导航入口
  • Articles 应该作为概念引导，不要写成 API 参考的复述
  • 合理使用 Deprecated 标签，让过滤器帮助开发者排除过时内容
  • 导航树的层级不要太深——3 层以内最佳，超过 4 层就很难浏览了

还有什么值得关注

  • Swift-DocC 的 Web 发布体验在持续改进，导航功能是今年最重要的新增
  • Tutorials 类型的内容在过滤器中有独立入口，适合循序渐进的教学内容
  • 文档页面的图片（PageImage）也会出现在导航树中，提升视觉辨识度
  • 参考 Apple 自家框架的文档组织方式是最好的学习途径
WWDC 2022