When Apple unveiled DocC two years in the past, I don’t suppose 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 nice shock once we realized it may 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 device’s capabilities had stopped. However there was one large shock left with it with the ability to produce totally interactive tutorials, like the Apple-authored ones they created to show SwiftUI. It is sensible for Apple’s inner groups to all use the identical device quite than having a “documentation device” and a “tutorial device”, however I nonetheless didn’t anticipate 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 outdoors Apple be keen to place the work in to make them?
So I’ve been idly preserving monitor each time I spot one within the wild, and whereas I’d not name them frequent, there are nonetheless loads round, and I’d like to showcase a number of for you right this moment.
They’re even used to create coaching/workshop materials, which I didn’t anticipate.
It’s incredible to see folks put effort and time into creating such high-quality tutorials. Nonetheless, should you 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 think about including the “icing on the cake” with a tutorial after that.
It’s nice to see such a powerful 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 Package deal Index at some point. It’s greater than we anticipated!
Dave Verwer 