この記事は何？
DocCドキュメントを作成するためのTutorialについて、Apple開発者向けドキュメントを読む。
ディレクティブの階層
Tutorialページ
- Tutorial（←これ）
- XcodeRequirement
- Intro
- Image
- Video
- Section
- ContentAndMedia
- Steps
- Step
- Code
- Image
- Image
- Video
- Code
- Step
- Stack
- ContentAndMedia
- Image
- Video
- ContentAndMedia
- Image
- Assessments
- MultipleChoice
- Choice
- Justification
- Image
- Choice
- MultipleChoice
Tutorialディレクティブ
インタラクティブなコーディング演習を通じてSwift APIを学べる、チュートリアルページを表示する。
@Tutorial(time: Int?, projectFiles: ResourceReference?) {
@Intro(title: String) { ... }
@Section(...) { ... }
}
Parameters
- time
指定は任意。チュートリアルを完了するまでにかかる推定時間（分単位）。 - projectFiles
指定は任意。コードベースのアーカイブ名と拡張子。読者はチュートリアルの手順に従って、ダウンロードまたは参照できる。
Overview
@Tutorialディレクティブは、一連のステップを通じてSwift APIを学べるチュートリアルページの構造を定義する。
チュートリアルには、1つ以上のチュートリアルページを含めることができる。
なお、読者は@Tutorialsディレクティブで定義された目次ページから移動する。
この画像は、目次ページの始まり。
チュートリアルページの作成方法
チュートリアルファイルをドキュメントカタログに追加し、ファイル名が.tutorialで終わることを確認する。
そして、以下のテンプレートを貼り付ける。
@Tutorial(time: <#number#>) {
@Intro(title: "<#text#>") {
<#text#>
@Image(source: <#file#>, alt: "<#accessible description#>")
}
@Section(title: "<#text#>") {
@ContentAndMedia {
<#text#>
@Image(source: <#file#>, alt: "<#accessible description#>")
}
@Steps {
@Step {
<#text#>
@Image(source: <#file#>, alt: "<#accessible description#>")
}
@Step {
<#text#>
@Code(name: "<#display name#>", file: <#filename.swift#>)
}
}
}
}
完了時間を見積もる
オプションのtimeパラメータを提供することで、「チュートリアルが完了するまでにどれくらいの時間がかかるか」を読者に知らせることができる。
完了時間の見積もりは、読者がAPIを学ぶために必要な時間を理解するのに役立つ。
@Tutorial(time: 30) {
...
}
個々のチュートリアルに見積もりを設定しておくと、目次ページのイントロで「チュートリアル全体の合計完了時間の見積もり」を自動的に計算し、表示できる。
ソース資料の提供
ダウンロード可能な資料（サンプルプロジェクトやコード例など）をチュートリアルに追加したい場合は、アーカイブしてドキュメントカタログに追加する。
例えば、読者がステップのコードを追加する土台となるプロジェクトと、作業と比較するための完成プロジェクトを提供する。
プロジェクトファイルはドキュメントカタログのどこにでも保存できますが、リソースフォルダで一元管理すべき。
ドキュメントカタログにチュートリアル用フォルダを作成すれば、チュートリアル固有のものを作成することもできる。
プロジェクトファイルを読者と共有するには、projectFilesパラメータにアーカイブの名前と拡張子を入力する。
@Tutorial(time: 30, projectFiles: "SlothCreatorFiles.zip") {
...
}
イントロ部分について
チュートリアルのページは、@Introディレクティブで定義されたイントロダクションから始まる。
イントロダクションは読者が最初に見る部分なので、コンテンツに惹き込み、何を期待するかを知らせる。
セクションの背景として機能するテキストと画像、またはビデオへのリンクを含めることができる。
@Tutorial(time: 30) {
@Intro(title: "Creating and Building a Swift Package") {
This tutorial guides you through creating and building a Swift Package. Use the package to add your own re-usable classes and structures.
@Image(source: "creating-intro.png", alt: "An image of the Swift logo.")
}
...
}
一連のステップ
チュートリアルのページには、読者が行う一連のステップがある。
それらのステップは論理的なセクションに編成される。
例えば、そのチュートリアルは「Swiftパッケージの設定をガイドするセクション」とは別に「そのパッケージにクラスの追加するためのセクション」があるかもしれない。
@Tutorial(time: 30) {
@Intro(title: "Creating Custom Sloths") {
...
}
// 最初のセクション
@Section(title: "Create a Swift Package in a new directory") {
@ContentAndMedia {
...
}
@Steps {
@Step {
Create the directory.
@Image(source: "placeholder-image.png", alt: "A screenshot showing the command to type in the terminal to create the directory.")
}
@Step {
Create the Swift Package.
@Image(source: "placeholder-image.png", alt: "A screenshot showing the command to type in the terminal to create the Swift package.")
}
@Step {
...
}
@Step {
...
}
}
}
// 二つ目のセクション
@Section(title: "Add a customization view") {
@ContentAndMedia {
...
}
@Steps {
...
}
}
}
習熟度をチェックする
@Assesmentsディレクティブを使用すると、読者の習熟度を評価するためのセクションを作成できる。
評価セクションには、一連の選択問題が含まれる。
読者が回答を間違えた場合はヒントを提供して、再び回答できる。
@Tutorial(time: 30) {
@Intro(title: "Creating Custom Sloths") {
...
}
@Section(title: "Create a new project and add SlothCreator") {
@ContentAndMedia {
...
}
@Steps {
...
}
}
...
@Assessments {
// 問1
@MultipleChoice {
What element did you use to add space around and between your views?
// 不正解の選択肢
@Choice(isCorrect: false) {
A state variable.
@Justification(reaction: "Try again!") {
Remember, it's something you used to arrange views vertically.
}
}
// 正解の選択肢
@Choice(isCorrect: true) {
A VStack with trailing padding.
@Justification(reaction: "That's right!") {
A VStack arranges views in a vertical line.
}
}
// 不正解の選択肢
@Choice(isCorrect: false) {
...
}
}
}
}