Improve the discoverability of your Swift-DocC content

♪ Mellow instrumental hip-hop music ♪ ♪ Hi! My name is Bea, and I'm a human interface designer on the Documentation team. I'm going to share how to improve the discoverability of your Swift-DocC content. In this session, I'll talk about the new navigation experience available for Swift-DocC documentation on the web and share tips for how to optimize your content for discoverability. If you need some additional context on what Swift-DocC is and how you can make great documentation for your frameworks and apps with it, check out these other WWDC sessions.

Now, let's jump in and check out the new navigation on the web. This year, when you publish your documentation site, you get a new navigation experience that brings out the best in your content. The page contains two main sections. To the left is a navigator and filter bar that allow you to navigate through your documentation and find APIs quickly. To the right is the content view. It's optimized to be flexible in multiple screen and navigator sizes. Since the navigator is separate from the content, it's easy to quickly switch between different pages. You can also use the disclosure indicators to explore deeper in the tree and understand the API hierarchy. All of these features make it way easier to explore documentation. On the other hand, if you know what you're looking for and you want to get there as quickly as possible, you can use the Filter bar to refine the results in the navigator. Let's see the filter in action. Let's say that you're looking for "Habitat." When you click on the Filter bar and type that in, you'll get a filtered view of the pages you actually care about, right now. You can clear the filter to reset the navigator. And you can also filter to see articles, tutorials, and even hide deprecated pages by selecting tags. For example, if you select the Tutorials tag, it's super convenient to find the "Meet SlothCreator" tutorial. Now that you're up to date with what's new in navigation, I'm going to talk about how to make the most out of this new experience. Here are some tips and tricks for how you can optimize your content so developers find the pages they're looking for as smoothly as possible. Let me show you how I optimized the documentation for my framework, SlothCreator, as an example. You can use SlothCreator to catalog sloths you find in nature and to create new, adorable virtual sloths. I just finished working on my framework documentation, so I haven't written any markdown to organize my pages yet. As a starting point, I'm taking advantage of Swift-DocC's automatic organization. This means my navigator is organized by types, like tutorials, articles, protocols, and structures. This is already a great start, but I can do a better job guiding developers through my documentation. To optimize my content, I'm going to follow three steps.

First, define the main high-level themes of what I can do with this framework. Then, I'll organize my pages by importance and specificity. Last but not least, I'll optimize my group titles to make sure they're as clear and helpful as possible. I think of this process as creating a map. It helps people understand the boundaries and general characteristics of a region and figure out how to get from one place to another. Likewise, the documentation navigator helps developers understand what you can do with a set of APIs and how to navigate to the pages they're looking for. I'll start by helping developers understand what they can do with my APIs by defining the main high-level themes of SlothCreator. These themes will show up on the navigator on the SlothCreator page, the top-level page of my documentation. It'll be one of the first things developers see when they land on my documentation website. This is my opportunity to make a great first impression and help developers have a good understanding of what this framework does. Now, let me think about my first theme. One of the main functionalities of SlothCreator is creating sloths. They have names, colors, and even special powers. To summarize, I'll call this topic group "Sloth Creation" Later, I'll decide what pages to include in this group, so I'll just leave a placeholder for now. After you create a sloth, you can visualize it in many different ways, like on an app screen, in a map view. I'll call this "Sloth Views" And of course, sloths are a lot of work. They need to be fed, entertained, taken care of. I'll call this "Management" There's already a lot of functionalities you can achieve in these three groups. And putting myself in the shoes of a developer who's never used SlothCreator before, I'd love to have an easy way to see how to get started with this framework. With this in mind, I'll create a topic group with high-level introductory content. I'll call it "Essentials." Awesome! Even though there are hundreds of things you can do with SlothCreator, I'm only highlighting the four most important, overarching topic groups. By reducing the number of options that are available, I'm increasing developers' chances of successfully taking the next step. There's no magic number for how many topic groups I should create, but I generally try to stick to under 10 per page. Thinking back to the idea of a map, I want to give developers step-by-step guidance on where they can go next. The order of my groups is vital to create a great experience. Taking another look at my topic groups, they're mostly in a good order. First, you have to create a sloth, then you can visualize it, then you can manage it. The only thing I'd change here for now is moving Essentials up to the beginning of the list, so developers see that beginner content first. Now, it's time to decide the pages and themes that should be organized under each one of these categories. Let me start with Essentials. This will be at the very top of the navigator and probably one of the first things developers will see. So I want to make sure this features the most important introductory content. This is a great spot to highlight introductory articles and tutorials. This enables developers to find step-by-step code examples quickly, which is, personally, my favorite way to learn. With these considerations in mind, I decided to organize three groups under Essentials: the "Meet SlothCreator" tutorial, the "Getting Started with Sloths" article, and the Sloth struct, one of the core APIs in my framework. I'll repeat this same process for the three other groups. This feels approachable because I see the most important and broad themes first. As I explore deeper in the tree, the groups get more specific and advanced. For instance, inside Essentials, I'll find Getting Visual Attributes. And inside Getting Visual Attributes, I'll find Getting the Standard Colors. Great, my documentation is organized in a way to guide developers through the content successfully. Next, I want to make sure the titles of my topic groups are also high quality. The first characteristic to a great topic group title is that it should be clear and descriptive. A good title makes sense on its own and doesn't need much additional context. Thinking back to my topic titles, there's some room for improvement. The last topic title I wrote is "Management." This group of APIs is all about what you can do to manage your sloth's well-being: Activity, CareSchedule, FoodGenerator, and Sloth.Food. At first glance, this seems like a good title. However, upon further consideration, "Management" is such a broad term; it could mean a ton of different things. So it's not ideal. To make this clearer and more descriptive, I'm going to call it "Care and Feeding." Now, I understand this group is all about taking care of my sloths and giving them food. For that reason, it's also important that topic group titles be mutually exclusive. If I have titles that are interchangeable, it's hard to know which one contains what I'm looking for. For example, Fueling Superpowers, Getting Magical Abilities, and Casting Enchantments are very similar themes and could probably be organized under a single title. By keeping the names as mutually exclusive as possible, I'm making it simpler for developers to figure out where to go next. The more work I put into organization and page titles, the more likely developers will have a smooth path to the page they're looking for. Also, the more likely I'll encourage serendipity; in other words, happy accidents. By organizing well-thought-out themes next to each other, I'm enabling developers to find relevant, related pages. For example, as I'm learning about SlothCreator Essentials, I'm delighted to find Getting Magical Abilities in the list. All of these tips and tricks really brought my documentation to the next level. It's so much better! Now, let's review how you can improve the discoverability of your content and make it approachable for developers. First, identify the main themes of your documentation. Then, organize your content by importance and specificity. Next, encourage serendipity, by organizing related themes next to each other. Last but not least, write clear, mutually exclusive titles for your pages and groups. Thank you for taking the time to learn how to make your documentation better. I'm sure developers will deeply appreciate it. Have a great WWDC! ♪