The Documentation Workgroup will be holding its next meeting on Monday, April 7th, 2025 from 8:00am to 9:00am PT (or see the time in your own timezone).
This meeting will be open to anyone who wishes to contribute. If you wish to participate, please reach out to @swift-documentation-workgroup in forums via DM for a link to the WebEx meeting.
Meeting notes for this meeting will posted in this thread shortly after.
Please propose agenda items in this thread.
@Joseph_Heck proposed an agenda item in https://forums.swift.org/t/topic-s-for-discussion-next-meeting/79129
I assume "Monday, February 24th, 2025" is a copy-paste typo here? @franklin
yeah, I think he meant today - in about 10 minutes as I'm writing this
Yes, sorry!
Notes from today's meeting:
Kyle - for pre-release tags, what happens in SPI when a full release version is deployed. The use case is sometimes we need to tweak about the SPI file since we can't reproduce it locally. It may envolve multi round of commit to play with it. And It currently will need to push into main or create a pre-release tag as you suggest.
Dave - the docs are built when the initial pre-release tag is identified, and it dropped in favor a full release when a full release tag is available.
Sven - I'd just tack -rc-1… rc-2 - that way it also gets built immediately. But actually I do not want it to be released at all since it was just some local play. it wouldn't be a release, SwiftPM won't see those either, I believe.
Joe: Documentation is claimed in the charters by both this workgroup and the website workgroup. This workgroup seems to focus more on documentation tooling and publishing outside of swift.org. Kyle Murray brought TSPL out into open source, and while not currently part of this workgroup, that content is managed by internal Apple employees, so I thought there was a bit of a carve out for that specifically.
David: There's also the Infromation architecture effort that spun out of the website workgroup, which is focused on content and providing some goals on where and how to organize it, particularly to reduce duplication and improve findability.
David: I've seen this group has been more historically focused on tooling.
Joe: For those who don't know, I've joined Apple full time, working on documentation for Swift outside of the core Apple platforms. I'm in the process of establishing a proposal for how to support an open-source contribution path, particularly to articles and that sort of content, that have historically been hosted on swift.org. As I go to promote that as a formal proposal, I wanted to understand the roles of the workgroups for making those proposals.
Franklin: I see us more as an in a steering position. If there's architecture needs that have tooling requirements, that's something we're tracking, as well as topics such as improving the user experience of documentation.
Joe: To outline more specifically what I'm thinking about, I'm focused on a path for article content - guides and such, with a starting point of the server guides that are currently somewhat scattered as markdown within the swift-org-website. I'd like to have that content hosted within DocC catalogs, either within a large mono-repo or individual repositories whose committers align to the subject matter experts. The goal being to work with Mishal and the Swift.org infrastructure teams to have a process to go from github pull request -> publishing the content. I'm working on socializing these ideas and getting feedback, with a goal of making a more formal proposal in the forums down the road with review by relevant workgroups.
Franklin: Some are interested in content to tooling and some more the content itself. Theming is one area, something that's been discussed recently and we're interested in achieving.