SwiftPM Snippets are an incredibly powerful tool for documenting Swift packages, and a comprehensive guide to using them has been one of the most commonly-requested items over the past year.
I would like to specially recognize SSWG members @Joannis_Orlandos and @tiborbodecs for their work publishing this article, which showcases one of many instances of mutually supporting efforts between different parts of the Swift Project.
Although we could have easily written and published this article in plain Markdown, writing the article in DocC and publishing through SwiftOnServer’s infrastructure allows us to provide a richer documentation experience and field-test our native Swift documentation tooling. We hope that this Snippets tutorial not only serves as a teaching aid for how to use SwiftPM Snippets, but also as a self-demonstration of what is possible with Swift documentation today.
You can read the full tutorial below!
As a reminder, SwiftOnServer is always looking for guest writers, so if you have an idea for an article and are eager to dive into the cutting edge of Swift documentation, please get in touch!
You can also get involved with the SwiftOnServer website itself, on GitHub.
i think it would make a lot of sense to add a brief overview, or even just a link to the SwiftOnServer article under the Add Code Listings section of the Formatting Your Documentation Content page.
I'll likely open a PR this week, I'm a bit torn on linking to the SwiftOnServer article though...
On one hand, the article was "blessed" by SSWG and SDWG so it's more official than some random blog, on the other hand it feels a bit strange to me to link to an external website. Thoughts?
hosting everything under swift.org is a non-goal, we want to cultivate a thriving community around the language and we won’t be able to do that if we’re stingy about linking to external sites from the toolchain docs.
It's a fantastic article, but I wouldn't stress too much about "blessed".
The DocC contents definitely should have this included, and I was also leaning towards taking some time to write something up for it, but hadn't yet made it beyond collecting all the specifics to start to create an outline for an article - so if you have something go for it.
That said, I personally wouldn't want DocC's formal documentation to rely on any content outside of what it's providing. Services and external sites come and go, and if it's a feature of DocC, then it really should be in the documentation FOR DocC.
The article on SwiftOnServer is fantastic, I don't want to take away from it in any way. I don't think they were obliged in any way to add it to DocC, but I do think the documentation for DocC should be provided BY DocC, and not expect it to be provided from any external sources, however closely tied to the ecosystem they happen to be.
@JacobHearst - If you want to collaborate on a contribution of documentation of snippets to add into DocC's content, I'd be more than happy to work with you on it.
I was also leaning towards taking some time to write something up for it, but hadn't yet made it beyond collecting all the specifics to start to create an outline for an article - so if you have something go for it.
@JacobHearst - If you want to collaborate on a contribution of documentation of snippets to add into DocC's content, I'd be more than happy to work with you on it.
I don't have anything put together so if it's something you've been thinking about then I'll leave it to you! I've just been trying to be more involved with the Swift project and this seemed like a gap that I could reasonably fill if there were no plans otherwise.