Documentation Workgroup Meeting - 11 August 2025
hackmd notes: Documentation Workgroup Meeting - 11 August 2025 - HackMD
Attendees:
- Joe Heck
- Sven Schmidt
- David Ronnqvist
- Jesse Haigh
- Vera Mitchell
- Franklin Schrans
- Sofia Rodriguez Morales
Discussion:
- (Joe) follow up copy-to-clipboard with a "selective line highlighting" feature in codeblocks (in articles). Share the use cases we've collected, talk about how to enable it, and invite any feedback.
- (Dave & Sven) discussed the multi-target thing from the last meeting, and we'd like to chat about that briefly, too
Action Items
- Welcome Jesse (they/them) - joining Joe to work on DocC feature additions, around code blocks
Copy to Clipboard Feature
Joe: Extending DocC with additional metadata to provide alternate displays for code blocks - #15 by QuietMisdreavus up and pitched, leaning into making it a default - but wanted to check here before we leaned into that.
David: Definitely suggest continuing with the forum threads
Vera: This thread is where the discussion is already happening
Sofia: Don't see a hard reason not to offer by default
Franklin: UI only shows on hover, right?
Jesse: Saw some feedback that on-hover is not ideal for Mobile, so changed to always-on. Applied other updates suggested from Marcus.
Franklin: I think we have some different UI for narrow and desktop viewports, definitely worth getting feedback for the specific UI and patterns in use. One example, to take a look, when we show tutorials there's the interface on the right, where in narrow displays, there's a more traditional view to that.
Highlight sections feature
Joe: heading to get feedback on the specifics for how to wrangle the details of authoring how to highlight
Franklin: definitely lean into forums
David: ++ on using forums - provides an easier async mechanism to read and provide feedback
Vera: Having a written space makes it less difficult to get feedback from folks in different timezones. Single timeslot for a meeting constrains who you can hear back from.
David: Are these intended to land together?
Joe: Not the same PRs, but the same pieces
David: Wondering if we should add this as an experimental feature with a feature flag to extend this and build on the pieces. Leverage the experimental flag to let us land things experimentally. Can ask for feedback about the combined syntax for all pieces later, when proposing the enable them by default (no longer as experimental).
Multi-target docs feature
(example: Documentation )
Sven: We typically switch over to default rendering a week or two after 6.2, so earliest would - but you can specify a specific swift version. One thing that would be really important - not do our target merging with the official one. We'd stop doing ours in favor of our earlier setup.
I think the new version is a drop-in replacement for what we do - and adds more. Is there any support for target ordering in display.
David: I don't think so, You might get it yourself if you merge yourself.
Sven: that would be a slight regression then - right now the targets are listed in the order that you provide them in the .spi.yml
Sven: I think we'll want to keep a pull-down to choose the target. Does the synthesized page exist in all, or just combined?
David: Landed in 6.1, but synthesized page is only for combined archives.
Sven: I think what we want to do is use the landing page for multi-target archives, but keep our drop-down to select through to specific targets.
David: Biggest difference for you is that people would move their configuration to a package-level configuration vs. target/target config. The way this works is that it manages the orchestration to build and merges all the pieces.
David: I think it defaults to building all the products (targets linkable by package consumers) when you ask for the combined docs without specifying explicit targets. With the synthesized page on multiple tagets, the synthesized page could become the landing target.
Sven: Right now, you need to specify all the targets you want to generate. I wonder what we'll do w/ 6.2 going forward. I can see people wanting to have a custom list. The mixture of ordering from .spi.yml to ordering of the sidebar - want those to be the same.
Sven: Is there any way to interrogate an archive to understand if it's a multi-target archive?
David: There's a different file that there, and can be checked. Another you can check is the navigator index that has a list of the identifiers that are combined into it.
David: reharding re-ordering for list of targets - would need to look at it. Need to understand if it's a change in that the plugin can orchestrate from the outside, or it that needs to happen in DocC itself. If it can happen in the plugin, then we can make that work with 6.1. If it needs to happen in DocC, we'd need to land that in 6.3 at the earliest. Long term we want to let the author provide explicit ordering by authoring the top-level page.
Sven: Is the sidebar driven by a single JSON file?
David: Yes.
Sven: So it might not be outside of the realm of possibility that we could re-order that if that works.
Franklin: I think we need to update the metadata JSON file to reflect display names for multi-target archives.
Sven: Just in general, we need a good test target to make sure this lies out correctly.
Joe: Could use SwiftPM as an example, but there's FAR more target than you'd want to create.
David: We only have two targets in DocC, so that might be an option, and I have smaller synthetic examples that aren't really interestined to look at, but reflect the basic functionality.
Sven: I think I've hit all the high level pieces. I think we really need a good sample project.
David: for context, this is the DocC docs on GitHub pages that lived on this feature very early on
Swift Ecosystems Group mtg
Franklin: Waiting for a response from the ESG, looking forward to connecting with them when they create and pick a slot for that meeting.