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 pleasing shock after we realized 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 large 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 relatively 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 simple to learn, with screenshots that persist whereas the reader scrolls previous a number of tutorial steps, take a very long time to create. Would anybody exterior Apple be keen to place the work in to make them?
So I’ve been idly conserving monitor each time I spot one within the wild, and whereas I’d not name them frequent, there are nonetheless a lot round, and I’d like to showcase a couple of for you in the present day.
They’re even used to create coaching/workshop materials, which I didn’t count on.
It’s unbelievable to see folks put effort and time into creating such high-quality tutorials. Nevertheless, in the event you simply seemed by these and felt intimidated, keep in mind that any documentation is best than nothing. Begin with API reference documentation, go deeper with Markdown articles, and solely take into account 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 would 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!