Highlight
Swift-DocC 网页文档新增左侧导航栏和过滤器，开发者可以按主题层级浏览、按关键词搜索、按标签筛选；而文档作者通过 Topic Group 组织内容，能让使用者更快找到所需 API。
核心内容
文档写好了，开发者找不到
很多框架的文档按类型自动分组：教程、文章、协议、结构体……这种组织方式对熟悉框架的人够用，但对新手来说，面对几十个 API 列表，不知道从哪里开始。
Apple 文档团队的设计师 Bea 用”地图”做比喻：好的地图帮你理解区域边界、找到从一个地方到另一个地方的路径。文档导航也一样，要让开发者理解框架能做什么、怎么找到想要的页面。
三步优化文档可发现性
- 定义高层主题：把框架功能归纳成几个核心主题
- 按重要性和具体程度组织页面：先展示广泛的基础内容，再深入具体的高级功能
- 优化分组标题：清晰、互斥、有描述性
详细内容
新的网页导航体验
（00:49）
Swift-DocC 网页文档现在有两栏布局：
- 左侧导航栏：可展开的树形结构，展示 API 层级关系
- 右侧内容区：自适应不同屏幕尺寸
- 底部过滤器：输入关键词快速定位符号
- 标签筛选：按 Articles、Tutorials、Deprecated 等标签过滤
导航栏和内容区分离，切换页面时导航状态保持。展开 disclosure indicator 可以深入查看类型层级，不需要打开页面就能预览子内容。
过滤器支持实时搜索。输入 “Habitat” 后，导航栏只显示匹配的页面。选择 Tutorials 标签，能快速找到 “Meet SlothCreator” 这类教程页面。
从自动组织到手动策展
（02:56）
默认情况下，DocC 按类型自动组织文档：教程、文章、协议、结构体等。这是不错的起点，但可以做得更好。
以 SlothCreator 框架为例，Bea 定义了四个主题组：
# ``SlothCreator``
@Metadata {
@TechnologyRoot
}
## Overview
Create and care for virtual sloths.
## Topics
### Essentials
- <doc:Getting-Started-with-Sloths>
- <doc:Meet-SlothCreator>
- ``Sloth``
### Sloth Creation
- ``SlothGenerator``
- ``NameGenerator``
- ``PowerGenerator``
### Sloth Views
- ``SlothView``
- ``SlothMapView``
- ``SlothCard``
### Care and Feeding
- ``CareSchedule``
- ``FoodGenerator``
- ``Sloth/Food``关键点：
## Topics区域定义主题分组- 每个
###是一个 Topic Group，出现在导航栏中 - 用
<doc:Article-Name>引用文章，用`SymbolName`引用 API - 分组顺序很重要：先放入门内容，再放核心功能，最后放高级功能
定义高层主题
（04:15）
主题组是开发者进入文档后最先看到的内容。以 SlothCreator 为例：
- Essentials：入门内容，教程和核心概念
- Sloth Creation：创建树懒的核心功能
- Sloth Views：展示树懒的各种视图
- Care and Feeding：照顾和喂养树懒
每个页面建议不超过 10 个主题组。选项越少，开发者越容易做出下一步选择。
按重要性和具体程度组织
（06:44）
Essentials 组放在最前面，包含最重要的入门内容：
### Essentials
- <doc:Meet-SlothCreator> // 教程：一步步学习
- <doc:Getting-Started-with-Sloths> // 文章：概念性介绍
- ``Sloth`` // 核心 API其他组按使用流程排列：先创建（Sloth Creation），再展示（Sloth Views），最后管理（Care and Feeding）。
在每组内部，也遵循从广泛到具体的顺序：
### Sloth Views
- ``SlothView`` // 最常用的基础视图
- ``SlothMapView`` // 特定场景的地图视图
- ``SlothCard`` // 更具体的卡片视图关键点：
- 导航树越往下，内容越具体、越高级
- 先展示广泛的基础内容，再深入具体功能
- 这种层次结构让开发者能按自己的需求深入
优化分组标题
（08:05）
好的主题组标题有三个特征：
-
清晰描述：标题本身就能说明内容，不需要额外上下文
- 差：“Management”（太宽泛）
- 好：“Care and Feeding”（具体说明是照顾和喂养）
-
互斥性：不同组的标题不能互换
- 差：“Fueling Superpowers”、“Getting Magical Abilities”、“Casting Enchantments”（三个标题内容重叠）
- 好：合并成一个 “Magical Abilities” 组
-
鼓励意外发现：把相关主题放在一起
- 在 Essentials 旁边放 “Getting Magical Abilities”
- 学习基础内容时，开发者可能发现”原来还能这样”
组织结构的实际效果
优化前后的导航对比：
优化前（自动组织）：
SlothCreator
├── Articles
├── Tutorials
├── Protocols
├── Structures
├── Classes
└── Enumerations优化后（手动策展）：
SlothCreator
├── Essentials
│ ├── Meet SlothCreator (tutorial)
│ ├── Getting Started with Sloths (article)
│ └── Sloth
├── Sloth Creation
├── Sloth Views
└── Care and Feeding关键点：
- 自动组织按类型分类，对新手不友好
- 手动策展按功能主题分类，符合开发者的心智模型
- 主题组让文档首页成为一张”地图”
核心启发
-
给框架文档重写 Topic Group 组织 打开现有文档，看看是不是还在用自动组织的类型分类。把 API 按功能主题重新分组，给每个组起个清晰的名字。这是让文档从”能看”变成”好用”的最快方式。
-
为每个模块写一个 Essentials 主题组 把最重要的教程、入门文章和核心 API 放在 Essentials 里。这是新用户最先看到的内容，决定了他会不会继续深入。
-
检查分组标题是否互斥 看看文档里的主题组标题，有没有两个标题内容可以互换。如果有，合并它们或者重新命名，让每组有明确的边界。
-
在相关主题旁边放”意外发现”内容 基础内容旁边放一两个高级功能的链接。开发者在学习基础时可能发现”原来还能这样”，这种惊喜能提升对框架的好感。
-
用过滤器验证文档结构 发布文档后，自己用过滤器搜索几个常见关键词。如果找不到或者路径太长，说明组织结构还需要调整。
关联 Session
- What’s new in Swift-DocC — Swift-DocC 新功能总览，包含网页发布和 Objective-C 支持
- Build interactive tutorials using DocC — 用 DocC 创建交互式分步教程
- Create Swift Package plugins — Swift-DocC 的 Swift Package Manager 插件用法
- What’s new in Xcode 14 — Xcode 14 全部新功能总览
评论
GitHub Issues · utterances