Swift-DocCコンテンツを見つけやすくする

♪ 落ち着いた雰囲気のヒップホップ音楽 ♪ ♪ こんにちは Beaです Documentation teamの Human Interfaceエンジニアです Swift-DocCコンテンツの発見可能性を 向上する方法についてお話しします 本セッションではウェブ上のSwift-DocC で 利用可能な新しいナビゲーション体験の説明と コンテンツの発見可能性を 最適化するためのヒントを 共有します Swift-DocC とは何か これを使用しフレームワークや Appを作成する方法についての詳細は 他のセッションをご覧ください

ではウェブ上の新しい ナビゲーションについてです 今年ドキュメンテーションの サイトを公開すると 最高のコンテンツをもたらす 新しいナビゲーションを 使用できるようになります このページには２つの主要なセクションがあり 左には ナビゲータとフィルタバーがあり すばやく文書を検索し API を発見することができます 右はコンテンツビューです 複数の画面とナビゲータサイズで 柔軟性が高まるよう最適化されています ナビゲータはコンテンツとは別であるため 異なるページ間での切り替えが簡単になります また開示インジケータを使用し 構造をより深く探索し API 階層を把握することができます これらの機能はすべて文書の検索を 非常に簡単にします 一方で 検索内容を把握しており すばやくそこに到達したい場合は フィルタバーを使いナビゲータで 結果を絞り込むことができます 実際にフィルタを使ってみましょう 「Habitat」を検索したいとしましょう フィルタバーにそれを入力すると 現在自分が大切とするページが フィルタリングされて表示されます フィルタをクリアしてナビゲータをリセット またフィルタを使用してチュートリアルを表示 非推奨のページを非表示にもできます 例えば チュートリアルタグを選択すると 非常に便利に「Meet SlothCreator」 チュートリアルを見つけることができます ナビゲーションの最新情報を得たところで 新しい体験を最大限に活用する 方法についてお話しします デベロッパが探しているページを 可能な限り スムーズに見つけられるようコンテンツを 最適化するためのヒントやコツを共有します 私がフレームワークSlothCreator の 文書を最適化した方法を例にお見せします SlothCreator はナマケモノのカタログで バーチャルナマケモノを 作成するためのものです フレームワークの文書を完成したところで ページを編成するマークダウンは まだ作成していません 開始点としてSwift-DocC の 自動編成を利用します これでナビゲータはチュートリアル 記事 プロトコル 構造と種類別に編成されます これでも十分ですがデベロッパの文書の検索を ガイドするにはまだ改善の余地があります コンテンツの最適化には３つの手順に従います

最初にこのフレームワークで実行できる 主要な ハイレベルのテーマを定義します 次に ページを重要性と特定性で編成します そしてグループタイトルを最適化し 可能な限り明確で便利にします このプロセスはマップを 作成するようなものです ユーザが境界線やリージョンの一般的な性質を 理解しある地点から別の地点へと 移動する方法を理解するのに役立ちます 同様に文書ナビゲータもデベロッパが 一連の API で何が行えるか また 探しているページに移動するのに役立ちます では SlothCreator の 主要なハイレベルテーマを 定義することでデベロッパが私の API で 何ができるかをお見せしましょう これらのテーマはSlothCreator ページに 表示されます 文書のトップレベルのページです 私のドキュメンテーション ウェブサイトに行くと 最初に表示されるものです ここですばらしい第一印象を提供して デベロッパがこのフレームワークの内容を 把握しやすいようにします では 最初のテーマを考えてみましょう SlothCreator の主要機能の１つは ナマケモノの作成です 名前や色　特別な力を持っています このトピックグループを 「ナマケモノ作成」にします このグループをどのページに 含むかは後で決めます 今はプレースホルダを残しておきます ナマケモノを作成したらApp画面や マップビューなど異なる方法でナマケモノを 視覚化できます 「ナマケモノビュー」と名付けましょう もちろん ナマケモノの面倒を見るのは大変です エサをあげ 楽しませ大切にする必要があり これを「管理」と呼びましょう この３つのグループでもすでに多くの機能を 達成することができます SlothCreator を使用したことがない デベロッパの身になって このフレームワークを始める方法を 簡単に確認できるようにしましょう これを念頭においてハイレベルの入門的な 内容を含んだ トピックグループを作成します これを「基礎」と呼びましょう すばらしいSlothCreator では 数百のことができますが最も重要な４つの トピックグループに焦点を当てます 利用可能なオプションを削減することで デベロッパが次の手順に移るチャンスを 高めます トピックグループをいくつ作成すべきか 決定的な数字はありませんが １ページにつき10件が好ましいでしょう マップというアイデアに戻りましょう デベロッパに次に移動する場所について 詳しい手順を伝えたいとします すばらしい体験を作るには グループの順序は重要です トピックグループをもう一度確認します 順序は悪くありません 最初はナマケモノを作成し 視覚化してから管理します ここで変更するのは 入門コンテンツが先に来るよう 「基礎」を一番最初にすることです 次は書くカテゴリで編成すべき ページやテーマを決めます 「基礎」から始めましょう これはナビゲータの最上部にして 一番最初にデベロッパの 目に留まるものになります ですのでこの機能を 最重要の入門コンテンツにします 入門的な記事やチュートリアルを 強調するのに最適な場所です これによりデベロッパは コード例の手順を詳細に確認できます 個人的に私が好きな学習方法です これらの内容を考慮し 「基礎」では３つのグループを編成します 「SlothCreator とは」のチュートリアル 「ナマケモノの仕組み」に関する記事 フレームワークのコア API 「ナマケモノ構造体」です 残りの３つのグループでも同じことを行います これなら最も重要で広範なテーマを先に 確認できるので取り組みやすくなります 内容をより深く探索すると グループはより具体的で高度な内容になります 例えば「基礎」には 「視覚属性を取得」があります 「視覚属性を取得」には 「標準の色を取得」があります これで私の文書はデベロッパに うまく内容を案内できるようになりました 次にトピックグループのタイトルも 高品質なものにします 優れたトピックグループのタイトルの性質とは 明確で記述的であるものです タイトル自体がわかりやすく 追加の文脈を必要としないものです 私のトピックタイトルを考えると まだ改善の余地はあるようです 最後に書いたタイトルは「管理」でした この API グループは活動 CareSchedule FoodGenerator Sloth.Food など ナマケモノの健全性を管理するためのものです いいタイトルに見えますが よく考えてみると 「管理」だと具体的ではありません いろいろな意味があります なので理想的ではありません これを明確で記述的にするために 「ケアと給餌」に変更します これでこのグループがナマケモノの世話をして エサをあげることだと明確になります この理由からトピックグループの タイトルは相互排他的であることが重要です タイトルが置き換え可能である場合 探している内容が どこに あるかわからなくなります たとえば「スーパーパワーの補給」 「魔法の力をゲット」「魔法をかける」などは テーマが非常に似ているので １つのタイトルに編成できるでしょう タイトルを相互排他的にすることで デベロッパは次にどの内容に 移動すべきかがわかりやすくなります 編成とページタイトルに細かく取り組むことで デベロッパはよりスムーズに ページを検索できるようになります また セレンディピティ 別名「うれしい偶然」を奨励します 熟考して作成したテーマを隣り合わせにすれば デベロッパは適切なページを 見つけやすくなります 例えば SlothCreator の基礎を学んでいる場合 そこに「魔法の力をゲット」があれば最高です これらのヒントや技で 私の文書はレベルアップしました かなりいいものに仕上がりました では皆さんのコンテンツの発見可能性を改善し 親しみやすくする方法についてのおさらいです まず 文書の主要なテーマを特定します 次に重要性と特定性別に内容を編成します 次に関連する内容を隣り合わせにすることで うれしい偶然を奨励します 最後にページとグループには 明確で相互排他的な タイトルをつけることです よりよい文書の作成方法を ご覧いただきありがとうございます デベロッパの皆様に喜 んでもらえると思います WWDC をお楽しみください ♪