WWDC Quick Look 💓 By SwiftGGTeam
中文 EN 日本語
Improve the discoverability of your Swift-DocC content

Improve the discoverability of your Swift-DocC content

Developer ToolsDocumentationSwift
元の動画を見る

ハイライト

Swift-DocC Web ドキュメントには、新しい左側のナビゲーション バーとフィルターが追加されました。開発者は、トピック レベルで参照したり、キーワードで検索したり、タグでフィルターしたりできます。ドキュメント作成者はトピック グループを通じてコン​​テンツを整理し、ユーザーが必要な API をより速く見つけられるようにします。

主要内容

ドキュメントは書かれていますが、開発者はそれを見つけることができません

多くのフレームワークのドキュメントは、チュートリアル、記事、プロトコル、構造などのタイプ別に自動的にグループ化されます…この整理方法は、フレームワークに精通している人にとっては十分ですが、初心者にとっては、数十の API リストに直面してどこから始めればよいのかわかりません。

Apple のドキュメント チームのデザイナーである Bea 氏は、例えとして「地図」を使用します。優れた地図は、エリアの境界を理解し、ある場所から別の場所への道を見つけるのに役立ちます。ドキュメント ナビゲーションについても同様で、開発者はフレームワークで何ができるのか、目的のページを見つける方法を理解する必要があります。

ドキュメントの発見可能性を最適化するための 3 つのステップ

  1. 高レベルのテーマを定義: フレームワークの機能をいくつかの中核テーマに要約します。
  2. 重要性と具体性によってページを整理します: 最初に広範な基本コンテンツを表示し、次に特定の高度な機能を詳しく説明します。
  3. グループのタイトルを最適化: 明確で、相互に排他的で、説明的なものにします。

詳細

新しい Web ナビゲーション エクスペリエンス

（00:49）

Swift-DocC Web ドキュメントは 2 列のレイアウトになりました。

  • 左側のナビゲーション バー: API の階層関係を示す展開可能なツリー構造
  • 右側のコンテンツ領域: さまざまな画面サイズに適応します
  • 下部フィルター: キーワードを入力してシンボルをすばやく見つけます
  • タグ フィルタリング: 記事、チュートリアル、非推奨などのタグでフィルタリングします。

ナビゲーション バーはコンテンツ領域から分離されており、ページを切り替えるときにナビゲーション ステータスが維持されます。開示インジケーターを展開すると、タイプ階層にドリルダウンし、ページを開かずにサブコンテンツをプレビューできます。

フィルターはリアルタイム検索をサポートします。 「Habitat」と入力すると、ナビゲーション バーには一致するページのみが表示されます。 「チュートリアル」タブを選択すると、「SlothCreator の紹介」などのチュートリアル ページがすぐに見つかります。

自動整理から手動キュレーションへ

（02:56）

デフォルトでは、DocC はドキュメントをタイプ (チュートリアル、記事、プロトコル、構造など) 別に自動的に整理します。これは出発点としては良いですが、さらに良くなる可能性もあります。

SlothCreator フレームワークを例として、Bea は 4 つのテーマ グループを定義しています。

# ``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エリア定義トピックのグループ化
  • それぞれ###ナビゲーション バーに表示されるトピック グループです。
  • 使用<doc:Article-Name>記事を引用するには を使用します SymbolName “ リファレンスAPI
  • グループ化の順序は非常に重要です。最初に基本コンテンツ、次にコア機能、最後に高度な機能を配置します。

高レベルのテーマを定義する

（04:15）

トピック グループは、開発者がドキュメントを入力するときに最初に目にするものです。 SlothCreator を例に挙げます。

  • Essentials: 入門、チュートリアル、および主要な概念
  • ナマケモノの作成: ナマケモノを作成するためのコア機能
  • ナマケモノのビュー: ナマケモノのさまざまなビューを表示します
  • 世話と餌やり: ナマケモノの世話と餌やり

1 ページあたりのトピック グループは 10 個以下にすることをお勧めします。選択肢が少ないほど、開発者は次の選択をしやすくなります。

重要性と具体性によって整理

（06:44）

Essentials グループが最初に配置され、最も重要な入門コンテンツが含まれています。

### Essentials
- <doc:Meet-SlothCreator>           // 教程：一步步学习
- <doc:Getting-Started-with-Sloths> // 文章：概念性介绍
- ``Sloth``                          // 核心 API

他のグループは使用プロセス別に整理されています。最初に作成 (ナマケモノの作成)、次に表示 (ナマケモノのビュー)、最後に管理 (ケアと餌付け) です。

各グループ内でも、大まかなものから具体的なものまでの順序に従います。

### Sloth Views
- ``SlothView``      // 最常用的基础视图
- ``SlothMapView``   // 特定场景的地图视图
- ``SlothCard``      // 更具体的卡片视图

キーポイント:

  • ナビゲーション ツリーが下に行くほど、コンテンツはより具体的で高度になります。
  • 最初に広範な基本コンテンツを表示し、次に特定の機能について詳しく説明します
  • この階層により、開発者は必要なだけ深くドリルダウンできます。

グループタイトルを最適化する

（08:05）

優れたトピックグループのタイトルには、次の 3 つの特徴があります。

  1. 明確な説明: 追加のコンテキストがなくても、タイトル自体で内容を説明できます。
  • 悪い例: 「管理」 (広すぎる)
  • 良い: 「世話と食事」 (具体的には、世話と食事)
  1. 相互排他性: 異なるグループのタイトルを交換することはできません。
  • 悪いもの: 「スーパーパワーの燃料化」、「魔法の能力の取得」、「エンチャントのキャスト」 (3 つのタイトルは重複しています)
  • 良い: 1 つの「魔法能力」グループに結合
  1. セレンディピティを促進する: 関連するトピックをまとめます
  • 必需品の隣に「魔法の能力を取得する」を入力します
  • 基本的な内容を学習すると、開発者は「これはまだできることがわかった」と気づくかもしれません。

組織構造の実際の効果

最適化前後のナビゲーションの比較:

最適化前 (自動編成):

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

キーポイント:

  • タイプごとに自動的に整理されるため、初心者には不向き
  • 手動によるキュレーションは、開発者のメンタルモデルに沿って、機能的なテーマごとに分類されます
  • テーマグループはドキュメントのホームページを「マップ」にします

重要ポイント

  • フレームワークドキュメントのトピックグループ組織を書き直す 既存のドキュメントを開いて、自動的に整理されたタイプ カテゴリがまだ使用されているかどうかを確認します。 API を機能テーマに再グループ化し、各グループに明確な名前を付けます。これは、ドキュメントを「読み取り可能」から「使用可能」に変更する最速の方法です。

  • モジュールごとに Essentials テーマ グループを作成します 最も重要なチュートリアル、入門記事、コア API を Essentials に配置します。これは、新規ユーザーが最初に目にするコンテンツであり、これによってユーザーがさらに深く掘り下げていくかどうかが決まります。

  • グループ ヘッダーが相互に排他的かどうかを確認します ドキュメント内のトピック グループのタイトルを見て、2 つのタイトルの内容に互換性があるかどうかを確認してください。その場合は、それらをマージするか名前を変更して、各グループの境界が明確になるようにします。

  • 「セレンディピティ」コンテンツを関連トピックの隣に配置 基本コンテンツの隣に高度な機能へのリンクを 1 つまたは 2 つ配置します。開発者が基本を学ぶと、「まだこうなるかもしれない」と気づくかもしれません。この種の驚きは、フレームワークに対する好感度を向上させることができます。

  • フィルターを使用してドキュメント構造を検証します ドキュメントを公開した後、フィルターを使用して、いくつかの一般的なキーワードを自分で検索します。見つからない場合、またはパスが長すぎる場合は、組織構造を調整する必要があることを意味します。

関連セッション

コメント

GitHub Issues · utterances