Elevate your DocC documentation in Xcode

♪ Bass music playing ♪ ♪ Beatriz Magalhães: Hi, my name is Bea, and I'm a human interface designer on the Documentation team. My colleague Jack and I are going to talk about how to elevate your DocC documentation in Xcode. It’s now easier than ever to write and share great documentation. This year, we’ve integrated documentation for your Swift frameworks right into Xcode 13. In this session, we'll enhance the documentation of a framework we created: SlothCreator. You can use SlothCreator to catalog sloths you find in nature and to create new adorable virtual sloths. To make our existing documentation for this framework better, we'll go over what documentation page types are available in Xcode 13 and how to choose what's best for your content, how to organize the order of your APIs to tell a story about your framework, and how extensions can give you flexibility in how you write your documentation. I’ll start with a new Xcode feature: documentation page types. Xcode 13 has a brand-new feature called "Documentation Catalog," which enables you to create three page types you can view on the documentation window or on the web: reference, articles, and tutorials. Each project is unique and has different needs, but it’s usually good to have a diverse set of documentation. Reference provides concise, in-depth information about individual APIs in your library. This allows you to add text descriptions, code snippets, and relationships between different symbols. This is the backbone of your documentation. Articles are pages with free-form content. They’re great at giving the big picture of how a framework works and explaining how to complete a specific task. They often connect the dots between different symbols. Tutorials are a step-by-step walk-through of a project that uses your framework. It's great to understand how a combination of symbols work together by implementing it in practice. Framework adopters of all proficiency levels can benefit from tutorials, but it’s worth noting this is also a very beginner-friendly format. In this session, we’ll focus on articles. To see information on reference and tutorials, check out these other WWDC sessions. Before I start enhancing my SlothCreator documentation, I’ll check out what’s new in the documentation window. Now, you can see all of the Apple technologies as well as your own documentation right there in the navigator. Now, I’ll check out the current state of my SlothCreator documentation. I have my SlothCreator Swift package open in Xcode. I'm going to click on Product and then Build Documentation to bring up my documentation window. Scrolling through my SlothCreator framework documentation, I see that all my symbols are already covered by reference here, which is great. However, if I approach this page from the perspective of someone who's never used this framework before, it's not clear at a glance what it does. I can use a top-level article to paint the big picture. Top-level articles have a concise summary sentence, an overview with content like images and code snippets, and on the bottom, a topics section with a few symbols you want to highlight. To add an article, I need to set up my project with a documentation catalog. The documentation catalog is a file in the Xcode navigator that contains all my documentation files. Moreover, it lets me write new page types. This makes documentation quick to access at a glance and makes it easier for me to prioritize documentation in my day-to-day workflow. To do this, I can right-click on the SlothCreator Sources directory, which contains the sources for our SlothCreator target, and select New File. Then, I’ll scroll through the list until I find Documentation Catalog. I’ll name it to match my framework target: SlothCreator. Xcode gives me a top-level article when I create a documentation catalog. I’ll rename it to "SlothCreator" both in the project navigator and in the markdown. Now, let’s get started on our article. You write articles using Markdown. First, I’m going to add a summary that describes what my framework does in one sentence. Next, I'll add more in-depth information under the Overview title about the main functionalities of SlothCreator: research, care, and visualization. Lastly, I’m going to add an image so developers know at a glance what they’re looking at. I’d recommend adding images that are 2x in resolution and either Dark Mode-compatible or have a Dark Mode alternative. Don’t forget to include the proper naming conventions for your files. First, the name of your file: "sloth." Then, if your image is in Dark Mode, a tilde and the word "dark." Then, @2x to describe the scale factor. And lastly, your image file format, which in this case is .png. Now that I made sure my images are the right size and are named correctly, I’m going to open Finder and drag my assets into the Resources folder of my documentation catalog.

Next, I’ll add my image to the article Markdown. First, I added an exclamation point, then a description between brackets to make my image accessible, and lastly, the file name between parentheses. You might have noticed I didn’t type in "@2x" or "~dark." That’s because Xcode automatically selects the image, so all I have to type in is the image name itself. All right, I finished my top-level article. Let’s see what it looks like by building my documentation. I’ll click on Product and select Build Documentation again to bring up my documentation window. Awesome, SlothCreator has a clear high-level summary, an overview that gives more context on what this framework is for, and an image that illustrates the core concept of the framework at a glance. Now, someone that’s never used SlothCreator before can quickly understand the big picture of what the framework does. I can make this documentation even better by providing actionable first steps on how to get started with SlothCreator. A task article could help with that. I’ve prepared a task article ahead of time, and I’m going to open Finder and drag it into my SlothCreator documentation catalog.

This article has the goal of teaching folks how to create and care for a sloth, the core element of this framework. In terms of structure, it’s very similar to the top-level article. Both types can include text, images, and code snippets. The biggest difference here is in the content. To see those differences, I’ll build my documentation again by selecting Product and Build Documentation.

Then, in my documentation window navigator, I’m going to select Getting Started with Sloths. Great, this article provides more context around how to create a sloth, by describing its properties and traits. It also gives actionable steps on how to care for the sloth and form a suitable habitat. This will help people to adopt SlothCreator much faster. To recap, so far, I talked about all the different types of documentation you can author and what you can use each one for. I introduced a new Xcode 13 feature called "Documentation Catalog," which allows you to put all your documentation files in the same place as well as author new types of documentation. And I used it to create two articles that enhance my documentation by giving it more context and diving in a specific task. To author those articles, I used Markdown and the new files that we’re now supporting for documentation. Now, I'm going to hand it over to Jack, so he can talk about how you can make your docs even better by organizing your symbols and creating documentation extensions. Jack Lawrence: Thanks, Bea, those articles look great. Now that we’ve added some new pages, there’s another way I can help guide everyone through the framework. Earlier, Bea created a framework page with an overview for SlothCreator. At the bottom of the page, the DocC compiler automatically created a topics section with all of the Sloth framework’s documentation. This is a great start, but I think we can improve it. So let’s take a step back and think about the story we want to tell. SlothCreator APIs fall into three main categories: researching and creating sloths, caring for the health and happiness of your sloth, and viewing your sloth in its habitat. I can use these categories to organize the documentation pages in SlothCreator. Here are the top-level pages for the framework. First, I’ll put aside all but the most important pages. I can organize supporting types -- like speed and color -- under another page later. Next, I’ll organize the remaining pages into groupings centered around the features of SlothCreator. And finally, I’ll sort the groups and pages from least to most advanced. This new organization looks a lot more approachable, and framework adopters interested in specific features will know right where to look. Now we’ll update the documentation for the framework to use these themes. I have the SlothCreator project open and the built documentation. The compiler automatically adds a topics section to each page with default groups. But I can customize it with some extra Markdown. Earlier, Bea created a documentation catalog with a framework article. In the project navigator, I’ll select the SlothCreator Markdown file inside the documentation catalog. The template already includes a topics section for me to fill out. Starting with "Essentials," I’ll update the group title in the third-level heading. Then I’ll add a list of links to include in the group. I’ll begin with the "Getting Started" article, and the sloth type. To link to an article, I use the name of the file without the extension, using the doc URL scheme. To link to a symbol, I surround the name of the symbol in double back ticks. Using the categories I created earlier, I’ll organize all of the other documentation pages into groups, as well. Now I’ll rebuild and take a look at the changes. In the Product menu, I’ll select Build Documentation to rebuild. The documentation built, but I see a diagnostic generated by DocC, And it looks like I mistyped a link here. Let’s let autocomplete take care of it, so I’m certain it’s correct. Now I’m going to rebuild the documentation again using the Product menu to see if I resolved all of the issues.

Awesome, no more warnings. On the framework page in the documentation window, our new "Getting Started" article is the first topic everyone will see, followed by the main themes for SlothCreator in order of complexity. The documentation navigator on the left also updates to match each page’s topics section, so I can quickly find the page I’m looking for. Now let’s review how to organize your documentation. All of your pages are organized automatically, and you can customize with a topics section. To create a topics section, add a second-level topics heading. Then, add a group with a third-level heading, followed by a list of links to any other pages that you want to organize under the current page. You can add a topics section to any article, along with any container symbol like a class, structure, enumeration, or protocol. When you’re organizing documentation for your framework, consider the most important features and themes, and which APIs developers might use together to create an app. Move supporting pages under your primary documentation to add focus and clarity. And start with the basics and then introduce complexity progressively. Now that I’ve customized the groups on the framework page, I want to organize all of the documentation in SlothCreator, including types and their members. Documentation extensions give me the flexibility to choose how I write documentation for my APIs. I could add a custom topics section right in my source code, but I think it would be easier to review and maintain over time if this additional documentation was in a separate file. And I can use a documentation extension to do just that. First, I create a new Markdown file. I associate it with an API using link syntax in the title. Next, to improve the focus and clarity in my source code, I’ll leave the primary content -- like the summary and discussion -- in the code and extract the topics section.

When DocC builds, it merges each source comment and corresponding documentation extension into a single documentation page. With extensions, it’s simple to write and review the documentation, improve the framework’s generated interface, and provide a better documentation reading experience. Now, I’ll add a documentation extension to enhance the documentation for SlothCreator. First, I’ll take a look at the Sloth page before I make any changes. I have the documentation comment for the Sloth type, and I also have the built documentation. The documentation I wrote in the source code looks great, but the Topics section could be improved, and I can do that in a documentation extension. In the project navigator, I’ll right-click on the documentation catalog to add a new file. In the template chooser, I’ll select the Extension File template and name it "Sloth." Next, I’ll connect the extension file to the sloth type using a link in the title. I need to include the name of the module in the URL.

This might look familiar, because earlier my colleague Bea used this syntax to create the top-level framework article. Then I’ll add some customized groups in a topics section. Finally, I’ll rebuild using Product > Build Documentation to check out the result.

The content I wrote in the source code is still at the top, and the topics section I created in the documentation file is added after it. When I expand the page in the navigator, the navigator's updated as well. The changes that Bea and I made are done, and we’re ready to share them with the world. The documentation looks great in Xcode, and anyone can build it after they download the Swift package. I can also use the Export button in the navigator to export an archive that you can use to browse the documentation in Xcode without downloading or building the Swift package. And if I want to make it accessible to everyone, I can even publish the documentation on the web. And you can check out this related session to learn more. Now, let’s review how you can elevate the documentation for your Swift framework. First, create articles to introduce your framework and explain how your APIs work together. Next, organize your documentation into groups to improve navigation. Finally, add depth and detail to your API reference in documentation extension files. If you want to go even further, you can learn how to publish to the web and guide readers step-by-step with tutorials in these two related sessions. Xcode 13 is a huge update for documentation, and we’re so excited to see what you publish. Thanks for watching! ♪