使用 DocC 构建交互教程

Hi, my name is Will, and I'm a design manager at Apple. Today, with my colleague Hannah, I'll show you how you can use DocC to write interactive developer tutorials. Tutorials are a great way to teach developers the details of how your swift framework or package works, with step-by-step instructions to build real apps using your API. You may be familiar with some tutorials we've written at Apple. We created tutorials to introduce you to SwiftUI and Mac Catalyst. In these introductory tutorials, you learn the basics of those frameworks and build your skills by following step-by-step code examples. We've found that framework adopters love how quickly they can get started with new ideas presented in tutorials. To make writing these tutorials possible, we built a documentation compiler called DocC. DocC leverages markdown to convert plain text into a rich, interactive system, and this year, we've introduced DocC to Xcode, so you can write tutorials for your Swift package or Swift framework, too. DocC isn't only for developer tutorials. DocC can also build documentation for the Swift frameworks and packages in your project from source comments, which means for app developers, your dependencies can have documentation right alongside platform libraries in the developer documentation window.

And if you create Swift frameworks or Swift packages, you can write documentation for your adopters right in your source, so it's easy to keep up-to-date as you create and modify API. You write documentation comments with markdown to preserve readability in source, while providing a rich formatting experience for the documentation window. You can also write articles and organize all the API in your framework or package by adding a Documentation Catalog.

You can learn more about using DocC and configuring Documentation Catalogs in the sessions listed here.

In this session, I'll focus on writing tutorials.

Tutorials are a highly-interactive form of documentation, and in order to make authoring them easy, we've extended markdown to have directives. Directives provide structure to author content-like tutorials so you can focus on writing content with existing markdown syntax you might already be familiar with.

Developer tutorials are centered around building real projects, ideally apps. Tutorial apps should use the API in your framework in a realistic way.

For example, in the SwiftUI tutorials, we show you how to build an app called Landmarks that explores the core features beginners need to understand to get started with SwiftUI.

With Mac Catalyst, we teach you to build a Recipes app that explores the differences between iPad and Mac navigation idioms.

And now, my colleagues and I have been working on a new framework for creating, cataloging, and caring for cute little digital sloths right on your iPhone.

My colleagues have already written some great reference documentation and articles, but I think adopters of this framework will benefit from learning to build a real app so they can quickly see how the different aspects of the framework interact. In this session, my colleague Hannah and I will build tutorials to teach adopters of this framework the basics they need to get started with it. I'll start by giving you an overview of the main components of tutorials. Then I'll explain how I approach ideation and planning. And finally, I'll hand it off to Hannah, who will demo creating a collection of tutorials. All right. Let's get started. As I mentioned earlier, tutorials are a highly-interactive way to learn. And like article and reference documentation, the text of tutorials is authored in markdown, but tutorials use a special syntax to wrap this markdown in a directive that provides structure so DocC can build the complex layout and interactions featured in the tutorial.

This is a basic directive that tells DocC this text is a single step of a tutorial. Along with the instructive text, this example includes a link to a Swift file that DocC will display to show readers exactly what code to write to accomplish the step.

And DocC directives can be nested. In this case, the code directive contains an image directive that provides the reader more context for the step.

Tutorial pages have lots of individual steps, like the one we just looked at. The table of contents provides organization and links to the individual tutorials. Let's take a look at the directives of a table of contents.

The table of contents file starts with a Tutorials directive, which contains all the elements of the page.

Inside the Tutorials directive, there is an Intro directive, which includes a title and a brief description of what the framework adopter will build throughout the tutorials.

DocC generates some elements of the introduction, such as the "Get Started" button and timing calculation automatically when you provide links to the tutorials in the Table of Contents page.

The introduction also contains an image directive. You can store images in your documentation catalog resources folder. Down the page, you'll find a Chapter directive. You use chapters to organize tutorials into groups that make sense together. Chapters give framework adopters a clear sense of progress as they follow your tutorials, as well as provide context for what a framework is all about.

Inside the Chapter, there are individual links to tutorials. With all the context set by this page, framework adopters should have a good understanding for what the framework is and what they'll build with it before navigating to a Tutorial page.

Much like the table of contents, the Tutorial page starts with a single directive that contains the contents of the page. In this case, it's a single Tutorial directive.

DocC uses some information from the Table of Contents page in the tutorial introduction, letting folks know what the overall theme of this tutorial is by referencing the chapter it belongs to.

The introduction to the tutorial includes a title and description that tell the framework adopter which part the framework they'll use and what they'll build with it. To provide clarity along the path of building, tutorials are broken up into sections. Section introductions are very similar to tutorial introductions, but are specific to progress the framework adopter will make before moving on to the next section.

Sections contain steps, which instruct the adopter on what exactly they need to do to move on to the next step. Steps should be short, easy to understand, and easy to follow.

Framework adopters rely on consistent and clear tutorial steps to help them get up-to-speed on the framework they're learning about quickly. It's easier to create a cohesive set of steps throughout a collection of tutorials if you start with a clear plan. Let me show you how I make this plan by outlining a collection of developer tutorials for our new Sloth framework. In order to understand how to outline a framework, it's best to think about how the framework works and what the real-world uses are for it. Now, the framework my colleagues and I have been working on is all about sloths, and it provides quite a bit of cool functionality I'm excited to see people use.

Here's a high-level view of the main functionality in the framework. In order to outline my tutorials, I'm going to list the most important API so I can get a good idea of how to explain them through tutorials.

You can see there's API like the Sloth type itself, as well as a Food Generator and PowerPicker. If I try to think about these all at once, it's going to be tricky to decide how I should teach them in a clear order. So let me group them by general functional area.

I know understanding the Sloth type is really important for the adopters of this framework, so I'll group everything related to creating and editing the Sloth type. APIs used for generating sloths, giving them names, editing their powers: these are the core API used for creating sloths.

And it turns out, the remaining API, like food generator, care schedule, and habitat, are all related, as well. These API about taking care of sloths.

So, it looks like I have two main API groupings that make up the framework: the group of API that are about creating sloths and the group of API that are about caring for sloths. This is a great start. I know that adopters will need to understand these API to successfully use our framework.

And grouping them in this way will make it easy for me to show them how they function together. But I also know that adopters of this framework are likely to want to do more complicated things in their own apps.

So, I'll add another group. Our new framework is all about creating and caring for sloths, but I want to prepare folks to use it in ways that go beyond the API it includes, so I should include some information about interoperability. I think adopters are likely to use the framework to help sloths interact with other animals, move around different locations, or hang out in groups of sloths. I'm not trying to imagine every use case. I just want enough variety to introduce folks to ways they might use the framework in their own apps.

With these three groups, I have a great start organizing my tutorials. For now, I'll turn these groups into chapters, and I'll use them to brainstorm app ideas to let me teach the adopters of my framework how to use my API in a real app.

For the tutorials, I've designed an app that has features for each of these three areas. For creating, I'll make a simple view that lets users generate a new sloth and assign it a color and power. For caring, I'll give users the ability to see the sloth's general activity level, appetite, and mood. And for the interaction section, I'll make a feature that lets users find their sloths as they move around the world and interact with other animals.

With my app idea sketched out, I'm ready to plan how I'll build it and how I'll teach people to build it, too. I'll write a list of tutorials for each chapter that roughly follows how I'd go about building the app. First, I'd make the view for creating sloths. Then I'd work on the more complicated caring-for-sloths features. Finally, I'd build the parts of the app that use other frameworks.

After all this planning, I have a list of tutorials that I'm confident will help adopters of our framework create and care for sloths. This plan might change as I write, but for now, it'll help me organize my thoughts and make sure I've covered all the important API in a clear but not redundant way. So far, we've explored the directive syntax and the components that make up tutorials. We've also walked through the basics of outlining a collection of tutorials. At this point, we're ready to start writing, so I'll hand it off to my colleague Hannah who will show you how to write tutorials with DocC in Xcode 13. Thanks, Will. My name is Hannah. I'm a Human Interface designer here at Apple. Now that I have an outline of the SlothCreator Tutorials, with the all-new DocC feature in Xcode 13, let's walk through how to write a tutorial together.

My colleague, Bea and Jack, covered how to create a Documentation Catalog to organize documentation files in the session "Elevate Your DocC Documentation in Xcode." I'm going to add my tutorials in the same Documentation Catalog they created for SlothCreator. As Will mentioned, we need a table of contents file in order to compile the tutorials. So I've already created a Tutorials folder and a Table of Contents file for my SlothCreator Tutorials.

Now, let's start creating my first tutorial! First, I'll right click on the Tutorials folder, select New File to bring up the template selector, then select Tutorial file, click Next.

I'll name this tutorial "Creating Custom Sloths." DocC provides a template for me to start with. In the tutorial file template, there's an intro, a section, and a set of steps in the section.

If I want, I can show the estimated time of completion for my tutorial. I'll say it takes about 20 minutes.

Let's continue with the title of this tutorial. Here, I'll put in "Creating Custom Sloths." Then add my overview of this tutorial.

I want to make my tutorial look more engaging, so I prepared some art files for the tutorial intro, section intro, and steps. Let me open my Art File folder, select all the images I prepared, drag and drop them into the Resources folder in the Documentation Catalog.

Let me show you the intro image I designed. It visually describes what our framework adopters are going to build in this tutorial.

To add the intro image, I'll put in the image file name after "source." I'm also going to add an accessible description for the image.

I want my tutorials to be accessible to everyone so that every SlothCreator adopter can have a great learning experience through both reading and listening to the tutorials.

An accessible description describes what's self-explanatory to someone who's looking at the image. For example, I'll describe the intro image as "A wireframe of an app interface that has an outline of a sloth and four buttons below the sloth. The buttons display the following symbols, from left to right: ice, fire, wind, and lightning." Let's add the description in the code.

Now that I've completed the intro of this tutorial, let's move on to the first section.

This is going to be a beginner-friendly tutorial. So in the first section, our framework adopters will start with setting up the basics for the Slothy app. I'll put in the section title and add a description of the section.

I'm also going to add the section image I prepared, which visually represents the task flow of this section.

Similar to how I added the intro image, I'll put in the image file name and an accessible description.

Next, let's move on to steps.

In the first step in this section, our framework adopters will create a new Xcode project using the iOS app template. I'll put that in the instruction.

The media of this step should give adopters more context on how to do it, so I took a screenshot of Xcode's template selector and highlighted the areas they need to interact with.

One thing to keep in mind, when our framework adopters are viewing this tutorial, the background for Sections and Steps could be either light or dark based on their Xcode settings. So I can either create an image that is dark-mode compatible or provide a separate image for each appearance.

I'll add this image to the step.

Now I have added the first step, I'll go ahead and add the rest of the steps in section 1.

Okay. I've completed the steps in the first section. Let's take a look how this tutorial is coming along. In Xcode 13, I can preview my tutorials in the Developer Documentation window by navigating to Product Build documentation, or use the shortcut by pressing control+shift+command+D on the keyboard.

Great! The tutorials compiled successfully. And now, I can preview what I wrote in the Documentation Window that just popped up. Let's take a look at the Table of Contents page. On the navigator on the left, I can see my tutorials are organized under the SlothCreator project, along with other documentation my colleagues wrote for SlothCreator. On the right side, I can see the Table of Contents page. There is an overview for the tutorial collection and an eye-catching image in the intro section.

Below the intro, there's my first chapter and a link to the tutorial I just wrote. Let's take a look.

From the top of the Tutorial page, there's the tutorial intro, which tells our framework adopters that they will build a SlothCreation view, and it'll take them about 20 minutes.

Below that is the first section.

In this section, adopters will go through four simple steps to set up their project.

We can see the image updates as we scroll down the steps. So far, everything looks good. In the second section, our framework adopters will start coding with SlothCreator. Let's move on to see how to guide them with code steps.

I've already completed the intro of section 2 and the first step. Let's take a look at the second step, where our framework adopters are importing the SlothCreator package in the Swift file they created in the previous step. Before we dive into it, I want to point out a couple of things. A code step shows the display name on top, telling adopters which file they should be working on.

DocC will display the Swift file I'm adding for this step on the right side of the screen, below the display name.

DocC can also automatically compare the current code file with the one from previous step and highlight the new portion of the code.

This code file generates a preview. I can add a screenshot of the preview to this step so that adopters can check if they have followed the instruction successfully.

Let's go back to Xcode and finish this step. First, add the display name, then the code file name, and lastly, the preview image.

Now we've gone over how to add a code step, I'll go ahead and add the rest of the steps in section 2.

So far, we've walked through how to write a tutorial intro, a section, and different types of steps. Now, I'm going to add all the tutorials I've written for SlothCreator.

Let me open Finder, select all the tutorial files I prepared, drag and drop them into the Tutorials folder.

Next, I'll open the Table of Contents file, link the other two tutorials in the first chapter, then add the second and the third chapter.

Okay, now I have completed SlothCreator Tutorials. Let's take a look together. From the Table of Contents page, we can see this tutorial collection includes eight tutorials organized into three chapters.

I can also see this structure from the navigator on the left.

This page is a great way to provide our framework adopters a summarized view of this tutorial collection. Let's also take a look at the Tutorial page I just wrote. We have seen the intro and the first section, which guides our framework adopters through how to set up their project.

Below that is the second section that provides adopters clear coding instructions on how to build a sloth customization view.

Awesome! The tutorials look really good! I'm sure our framework adopters will be excited to learn about SlothCreator when they see my tutorials.

In this session, we went over what tutorials are, what makes a good tutorial, how to outline tutorials, and how to use DocC to write and preview tutorials.

DocC is a powerful new documentation feature in Xcode 13. With it, you can write comprehensive documentation for your framework, including reference, articles, and tutorials.

To learn more about how to write, build, and organize your documentation with DocC, I recommend you check out other DocC sessions from WWDC this year.

Thank you for learning with us, and we are thrilled to see what you are going to create with DocC in Xcode 13. [upbeat music]