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 
