Documentation Workgroup Meeting: 22 September, 2025

Swift Documentation Workgroup Updates
1

Documentation Workgroup Meeting - 22 September 2025

Attending

  • Franklin Schrans
  • Vera Mitchell
  • Kyle Ye
  • Joe Heck
  • Jesse Haigh
  • David Ronnqvist
  • Rauhul Varma

Topics

Joe Heck: Now that I've recovered, I wanted to revisit the whole concept of versioning, and patterns that can/should support it, navigation between versions, and more generally any suggested patterns for navigating inside a collection of multiple (but not an infinite number) of DocC archives

Joe Heck: Secondarily to that, the Website Workgroup redesign work is wrapping up it's focus on the community page and blog display (blog page design updates launched a day or two ago, if you didn't notice) - the next phase (3) is "Docs", and Mishal asked that I bring up and open the floor to how we use DocC and how to showcase it.
The top elements here:

  • How to include some manner of versioning (latest release, & dev/main to start) and building up to (latest release, previous release, and main) for docs collections.
  • How to wrangle navigation between versions and how to integrate this with DocC's internal navigation concepts/breadcrumbs.
  • Apply theming - header, footer, icons, fonts, and color treatments within docc collections to make any "swift docs" feel like part of the larger Swift.org website.
  • We have ~8 docc archives published at docs.swift.org, and I'm expecting to see that grow to loosely 12, maybe 14 - but not grow infinitely as we constrain what we cover to content focused on the swift language toolchain. If there's best practices or ways to integrate navigation between catalogs, we want to take advantage of it. It's generally the consensus that it's something we want to have on swift.org content.
  • Finally, are there any aspects of DocC that we should explicitly be showcasing for the archives that we publish on docs.swift.org and linking from swift.org - this is a more open-ended question, with a general desire from Mishal to ensure that any content we do present from swift.org & docs.swift.org showcases the use of DocC to it's fullest.

Discussion

Joe Heck: Versioning - want to leverage stable and latest release. How to wrangle versioning, is there a path for navigating between the versions within DocC-Render itself.

Franklin: Using URL prefixing to support multiple versions would make sense, following SPI's pattern. Custom header or footer nav is likely the only place to integrate today.

David: versioning almost needs to be wrangled outside of DocC's knowledge. Otherwise we might need support to allow us to inject some custom prefix into the existing breadcrumbs, but that's not a picker that allows you to transfer to another version.

Kyle: I don't think we want to add such logic in DocC. SPI only has a path to document 1 platform for the documentation, and you have to choose up front. One community member worked around this, merging multiple docc archives with different platforms to merge availability. Instead of introducing code to support broader navigation and ideas of versions, would prefer to see us build up more simpler tools to help coordinate and orchestrate.

David: Please don't try and merge different platforms of the same build. If there's a different symbol in both, there can be loss of information, as parts aren't mixed together. So that merging of different platforms to get availability isn't expected to work.

David: I feel like there's some things we can do if we know about versions, having links go the right pages, toggling between versions. Seems like a better long term solution. Only decision taht seems particular tricky to unwind is prefixing of the version URL scheme - and I suspect that's a good pattern to ingrain.

Rauhul: How does Apple's system wrangle API diffs?

Franklin: It's currently not supported on any site through open source.

Rauhul: If in the future it did, would the version be part of some query parameter URL?

Joe: I think rather than dynamic, the existing work is computed from the symbol graphs and then published - so no query links are used that process. But I've not done it and not entirely sure how it's wrangled. Assumed it was diffing of symbol graphs and some visual presentation of the results.

Kyle: Want to support a system that doesn't require external knowledge if possible. Should we be using a {platform}/{version} schema?

David: It's not something we do per-page today - rather there's different elements that are displayed together. not sure we'll need a path compoment for the platform.

Franklin: I'm not sure we want to support publishing docs for different platforms separately. That's something to explore, but not sure that would be a desirable user experience.
I think it makes sense to include version as part of the path, since that's a resource "on disk" vs. Diffs against something else. Query param would make sense if there's dynamic computation happening.

David: I think that makes for me as well. Language versions of the framework, for each you might want to diff between a number of arbitrary versions. That feels like dynamic behavior that would be better suited to a query parameter.

Rauhul: How is the ObjC vs. Swift selector handled today.

David: Page contains both ObjC and Swift information, and if availbale in both, the page displays the selector and which data is selected.

Franklin: The selector choice is stored in a cookie to provide that as a setting that hangs around. That cookie tends to be aggressive.

Rauhul: Wondering if you could filter based on Platform?

Franklin: Would you want that?

Rauhul: Would like to browse a superset, but be able to drill down to the specific platform I'm writing for.

Franklin: Today, DocC doesn't allow you to filter symbols at all. Or perhaps something to make it clear that symbols are specific to a single platform.

Franklin: Does anyone know how other languages support this?

Kyle: Mature system to handle different variants.

Vera: Story may have changed since I last looked, but Rust is awkward - selective surfacing symbols to the tool in a special compiler mode, tried to compile all platforms at once and surface them.

Franklin: Today you work from a symbolgraph per platform, providing all of them to one docc input to mix and match and generate the cross/multi-platform output.

Kyle: Yes, that's how the current mechanism that's been used by the community works.

Vera: Rust's approach from 7 years ago: the union of parallel universes | quiet misdreavus miniblog

Vera: the only thing in those earlier posts that might fall flat is mapping the target triples to what to call it - Linux vs. Mac.

Vera: That's the pattern I'd expect - a representative symbol graph for the platform that maps to the idea of that symbol being available for the relevant platform.

Kyle: Documentation
provides some linking with platform specific information within it.

Vera: Availability typically pulls from source and the availability symbol, which I think generates a token. Uncertain if there's one there for Linux and/or Windows.

Kyle: I wonder if we can pull this from the platform symbolgraphs, asserting availability.

Franklin: The speciics of which linux, or reliance on which LibC, gets really awkward to document - Ubuntu versions, BSD, etc. Unclear how to map the triples into a resulting "platform" name.

Vera: DocC has it's own conversion of the availability in the token/symbol graph - and it's unclear if it would handle external tokens as well.

Kyle: Don't have an example, but could build one - compile for each platform, and then bring them together to see how they work.

Franklin: That would be cool to try.

Joe: Second topic - as we redesign swift.org, how can we show case DocC to its fullest?

Rauhul - What's the option for providing updated theme content and how the page handles the site - icon updates, text font choices, etc - does the theme-settings.json cover allowing that to updated, or should it be an upstreamed PR to change the defaults and bring them a bit more up to date?

Franklin: Content correct, theming, and directives for complex layouts - notably TSPL would be nice to have a grid of items. HIG today uses the grid to add a visual flair to the index of the content. Might be good to go through the features of DocC - lots of directives to make content more digestable.

David: Various places you can display images as well to make it nicer. TSPL - image per page to categorize the pages perhaps? Places where you can do two column layouts. And For package documentation - can link back to the source code.

Joe: there's the combined catalogs in a single archive, and the mentioned-in mechanism. (mentioned-in as a mechanism is enabled by default now) SwiftPM is using the combined documentation mechanism to publish multiple catalogs into a single archive.

David: Example had a combined catalog with page images and such. Theming, adding images into pages with topicStyles directives of links directives.

Franklin: If we can publish the content somewhere, this workgroup is happy to look through it and see if we can wrangle results

Kyle: uncertain if we can customize the icon for class vs. actor vs. structure

David: You can, icon section of the themeing documentation.

Franklin: Not sure we'd want to change up all the doc icons in ordder to prevent someone from feeling list switching between catalogs.

Franklin: Is there a proposal in flight?

Rauhul: There was a forum post with a chrome extension, but maybe we reply to see if that person would be interested in contributing to upstream.

Joe: I'll follow up with the website workgroup and we'll see if we can wrangle some pre-published elements to review with this team to showcase DocC based on the catalogs we have up there today.

Kyle: Currently can't change some symbols through the themeing. Cool. But it seems I can't find the identifier for a struct/class symbol in the spec. swift-docc/Sources/SwiftDocC/SwiftDocC.docc/Resources/ThemeSettings.spec.json at main · swiftlang/swift-docc · GitHub

David: Oh.. I though that was supported. We may need to ask Marcus in the Forums

Action Items

  • Joe to follow up with the website workgroup, using the URL versioning scheme to support versioning. Nothing coming in terms of injected breadcrumbs to allocate.

  • Kyle identified that some theme elements (like the default class icon identifier) in the DocC render content can't be tweaked, so follow up with Marcus using Swift Forums to determine if we can/should add that theme capability.

(Editors note): I was yappin' too much during this meeting to take accurate notes since I brought up a couple of the topics, and the conversation around availability and handling platforms that Kyle brought up had far more detail than I was able to capture.

2 Likes