When Apple unveiled DocC two years in the past, I don’t assume anybody was too stunned to see it produce documentation from supply code remark annotations with Markdown formatting.
However that wasn’t all DocC did, and it was a pleasing shock once we discovered it might use Markdown for each navigation construction and long-form documentation to accompany your generated API reference.
Nobody would have raised an eyebrow if that’s the place the instrument’s capabilities had stopped. However there was one huge shock left with it having the ability to produce absolutely interactive tutorials, like the Apple-authored ones they created to show SwiftUI. It is smart for Apple’s inside groups to all use the identical instrument somewhat than having a “documentation instrument” and a “tutorial instrument”, however I nonetheless didn’t count on it.
The slight draw back is that these tutorials, whereas lovely and straightforward to learn, with screenshots that persist whereas the reader scrolls previous a number of tutorial steps, take a lengthy time to create. Would anybody exterior Apple be prepared to place the work in to make them?
So I’ve been idly maintaining observe each time I spot one within the wild, and whereas I’d not name them widespread, there are nonetheless lots round, and I’d like to showcase just a few for you immediately.
They’re even used to create coaching/workshop materials, which I didn’t count on.
It’s improbable to see individuals put effort and time into creating such high-quality tutorials. Nevertheless, if you happen to simply seemed via these and felt intimidated, keep in mind that any documentation is healthier than nothing. Begin with API reference documentation, go deeper with Markdown articles, and solely contemplate including the “icing on the cake” with a tutorial after that.
It’s nice to see such a robust begin from DocC. This remark is already too lengthy, however I’d write about what number of packages we see adopting it within the Swift Bundle Index sooner or later. It’s greater than we anticipated!
Dave Verwer 
