Documentation Workgroup Meeting - 17 Nov 2025
Attending
- Vera Mitchell
- Joe Heck
- Dave Verwer
- Franklin Schrans
- Sven Schmidt
- Sofia Rodriquez Morales
- David Ronnqvist
Discussion
Joe: I've got a few basic questions about convert vs process-catalog & process-archive and sort of what's intended within those.
David: Convert command - core conversation process. Process catalog and process archive are meant to work with only the catalog or archive.
Joe: I wanted to follow up from last weeks' conversation to see what coverage format outputs would be most optimal, or at least what controls of those we'd like to have (I think David had a gsoc suggestion along these lines, but I couldn't find it again)
Joe: Any ideas of an abstraction to plugin into DocC core rules? With Chris Mcgee's pitch on the forums ([Pitch] Documentation generation for any SwiftPM package), I was wondering how that settled in, and how we could not overload dependencies into it, but still let us include tooling that's external to the toolchain that it can use. Have been exploring alternate rendering, potentially using Toucan or one of the other several Swift community made HTML rendering tooling.
David: Some early discussions around tooling and such, but nothing concrete and most conversations stopped short of suggesting any specific API or abstraction layer.
Franklin: There were some ideas about including linters as well through plugins. There were some pieces there that were talked about being desired, but it didn't progress very far.
Sofia: There was also a plugin a few months ago focused on docc-render: [Pitch] Support for custom scripts in DocC, particularly for allowing external tooling in the JS app, but the DocC-Render maintainers would know more about it's status.
(post-meeting edit: The forum thread indicated that Lucca de Mello, who proposed the work, had some unexpected situations come up back in Jan and that proposal and PRs have stalled out a bit.)
Joe: coverage output - formatting and suggestions? Was there something specific that was useful there that we'd already worked out? I'm thinking of getting this up as "good first issue" kind of thing and encouraging community to help here.
David: Primary idea was to try and use the data, and work back into what's useful. Only design guidance is that I wanted to format to contain it's own metadata - e.g. columns have described headers, etc.
Sofia: Great that we're talking about docc being built into the toolchain commands. [GSoC 2025] Documentation coverage
Franklin: Would that impact anything with SPI and how it generates content?
Sven: When we started it would have been, but now it's pretty backed.
David: The possibly negative fallout is that plugin would be aligned with toolchain releases, offset by "feature" files that help align.
Joe: I'm not sure if Chris is aiming to mix in the plugin to the toolchain or do something alternatively.
Dave Verwer: If we do, does this make it more difficult to get something out quickly if needed?
David: Yes, I think so - it'd be locked in with toolchain builds.
Dave Verwer: Would we keep the plugin anyways?
David: Yes, if nothing else to allow additional features to be exposed and maintained.
David: SEO - continue discussion. Outputing some amount of documentation of how much content a page has? Something to experiment with. Is there a particular format that would be useful? Is it easier to have a CSV of number for filtering?
Joe: I missed this earlier - how are sitemaps wrangled today?
Dave: Sitemap for each area, and then sitemap for each DocC archive, which can be huge. Right now it's a page exists or is doesn't.
Sven: In terms of to put it - we pull from linkable entities today, so something in there as well might be really useful.
David: I probably don't want to add data to it, but there's other files we might be able to add to this. Indexing records might help us.
Dave Verwer: You don't have to give google everything, these are more considered the "places to start crawling" - so building a subset of pages with guaranteed content would be worlds better than what we have today - which is just listing every file.
Sofia: Can you ask Google to not index some pages
Dave: Can do that, but it's not so fine grained in our use. We use it to assert "older" documentation to ensure the "main" site is the indexed version.
Joe: Do we have any sense of the cycle time for experiments? Week? Month?
Dave: No way to really tell - not months, but hard to give any definitive answer here.
David: I am looking at the indexing records (-- emit-digest) one of it's fields is the full content - could could that as we process. Could count the length for each page.
Sven: Is this clearly human generated vs. automatically generated content?
David: I think so, need to double check. The purpose of the file is to have the text that a search engine could index to find them page. It doesn't have declaration or availability, it looks like it's just the text.
Franklin: Maybe we pick up SEO in another two weeks? It's Thanksgiving week in the US, but most of us aren't effected.
Dave Verwer: I'll be out for the next short bit, but that doesn't need to stop revisiting.
Action Items
- David to assemble a sample jq query or such to illustrate the index content that might be useful to filter on for wordcount to nail down more useful pages for a sitemap.