CommentComment

When Apple unveiled DocC two years ago, I don’t think anyone was too surprised to see it produce documentation from source code comment annotations with Markdown formatting.

But that wasn’t all DocC did, and it was a pleasant surprise when we learned it could use Markdown for both navigation structure and long-form documentation to accompany your generated API reference.

No one would have raised an eyebrow if that’s where the tool’s capabilities had stopped. But there was one big surprise left with it being able to produce fully interactive tutorials, like the Apple-authored ones they created to teach SwiftUI. It makes sense for Apple’s internal teams to all use the same tool rather than having a “documentation tool” and a “tutorial tool”, but I still didn’t expect it.

The slight downside is that those tutorials, while beautiful and easy to read, with screenshots that persist while the reader scrolls past multiple tutorial steps, take a long time to create. Would anyone outside Apple be willing to put the work in to make them?

So I’ve been idly keeping track every time I spot one in the wild, and while I’d not call them common, there are still plenty around, and I’d love to showcase a few for you today.

They’re even used to create training/workshop material, which I didn’t expect.

It’s fantastic to see people put time and effort into creating such high-quality tutorials. However, if you just looked through those and felt intimidated, remember that any documentation is better than nothing. Start with API reference documentation, go deeper with Markdown articles, and only consider adding the “icing on the cake” with a tutorial after that.

It’s great to see such a strong start from DocC. This comment is already too long, but I might write about how many packages we see adopting it in the Swift Package Index at some point soon. It’s more than we expected!

Dave Verwer  

Tools

Code




Design

Videos

Books

Jobs

Senior iOS Developer @ Linearity GmbH – We’re an award-winning design software suite that simplifies the asset creation process. Linearity Curve creates precision vector assets & Linearity Move is an animation software that crafts breathtaking animations in seconds. We’re crafting together a new iOS team, reach out if you're Interested! – Remote (within European timezones)

Senior iOS Engineer @ Luma AI – We are a small AI research and product company working on new kinds of creative tools for 3D. Our mission is to democratize the 3D experience for all. iOS at Luma is at the center of the product universe. We are growing the iOS team from 1-4, please reach out if you're interested! – On-site (United States in CA) with some remote work (within US timezones)

 

Would you like to see your company’s open positions listed above? Post your job over on iOS Dev Jobs, and check out with a “Featured Listing”, and they’ll be here next week!

 

And finally...

“Come over and see your old pals when you’re done to talking to that guy.”

Great stories.