Documentation Tooling Workgroup Meeting - 18 May 2026

Swift Documentation Tooling Workgroup Updates
1

Documentation Tooling Workgroup Meeting - 18 May 2026

Topics

  • GSoC
  • SEO updates (measuring)

Attending

  • Franklin Schrans
  • Matthew Bastion
  • Joe Heck
  • Padmashee
  • Prajwal Nadig
  • Sven Schmidt
  • Vera Mitchell
  • David Ronnqvist
  • Sofia Rodriguez Morales
  • Rahual Varma

Discussion

  • GSoC
    • Praj & Matthew mentoring for GSoC 2026 - extending VS Code & LSP for DocC related work.
  • Franklin: Where can the workgroup help?
  • Matthew: Expect most of this may well be in SourceKit LSP, but there may be some directive work as we flesh it out
  • Praj: After we build and sketch out features, would be great to have VSCode help with active use, feedback, etc.
  • Matthew: Right now we have previews, but that's about it.
    • VSCode -> SourceKit LSP -> DocC to return RenderNodes using Convert Service -> VSCode to render HTML content into a webview
    • As you change content, that flow updates live
  • Franklin: Curious how SourceKitLSP links DocC content
  • Padmashree: Talking about background indexing and storing symbols in a cache/store - but learning how that process works to start. Hoping to start with "Jump to Definition" first - click on symbol link, go to source.
  • Franklin: When we did the initial work to integrate into Xcode, we tried to keep all the critical pieces in the open source, but there may still be rough edges. Reach out if you find such, and we'll be happy to help navigate.
  • Matthew: Forums proposal should be available to everyone:
  • Franklin: Is there a specific timeline for this project?
  • Praj: coding is mid june to september, with two phases (end of july, phase 1, aug & sep phase 2)
  • Franklin: demo video of jump to definition https://drive.google.com/file/d/1usqHb21BipGkipx_s6OWjFgAq0aVyc4A/view
  • Padmashee:
    • click on link, extract and store symbol, then leverage the text search in VSCode to find the relevant place
  • Franklin:
    • RenderNodes expose symbols precise identifier (USR)
    • If you have access to the USR, that might be useful
  • Matthew: I think more of this will happen in SourcekitLSP to give access to more editors
  • Praj: The hope is that SourcekitLSP would broaden Swift support over a variety of editors (Vim, Emacs, etc)
  • Franklin: There was a recent change from an OSS contributor that caused the safari page to review during "preview"
  • SEO:
    • Joe: tracking updates for two packages (openapi-runtime and swift-configuration), they've been switched to HTML experimental output (6.3 builds, additional flag) and are published through SPI with those settings. Have verified that Google is indexing them. We've been capturing rankings for keywords for a couple of specific pages since December, and now since end of April when the packages were updated, one more capture and planning to report on deltas.
    • Joe: rankings could be a very weak signal, as the pages were reasonably well reflected in Google index before - so the additional HTML inclusion for the scrapers may have minimal effect.

Action Items

  • none Topics
2

Following up from our meeting -

I've been collecting data re: SEO impact for the two packages we tweaked back at the end of April, so we've got ~4 weeks of captures after the change, and acknowledgment that the pages are all indexed by google.

Two things stand out:

For the queries I was checking on DuckDuckGo, we have a clear and sustained improvement with the SEO content. Google, however, decided to drop on the Swift-configuration content. However, I suspect that's due to something else - Google appears to be ranking the GitHub repository for swift-configuration higher than the DocC content on Swift Package Index for those queries now.

I suspect adding a rel="canonical" tag into the relevant content, as Dave had mentioned earlier as a possibility, could have a real impact here of the latest version.

Most of the data is very solidly in the "not enough statistical relevance" zone, and another ~4 weeks of data capture would be needed to verify a trend from what I can see. (unsurprisingly, search result positions are pretty "noisy" in their positioning)

TOP 10 SPI IMPROVEMENTS BEYOND NOISE (symbol queries highlighted *)
  kind    engine      pre IQR        post med  Δ      keyword
  -----------------------------------------------------------------------------------------------
  *symbol duckduckgo  [12-26] med 26    6.5   +19.5  AccessLogger FileAccessLogger secret redaction
   phrase google      [26-26] med 26   10.0   +16.0  hummingbird configuration docs
  *symbol duckduckgo  [12-17] med 13    2.5   +10.5  ServerTransport protocol Swift
  *symbol duckduckgo  [2-9] med 5       1.0    +4.0  UndocumentedPayload error Swift
   phrase duckduckgo  [26-26] med 26   23.5    +2.5  swift server configuration docs
  *symbol duckduckgo  [4-6] med 6       3.5    +2.5  Swift OpenAPI Runtime

I do have the raw data, and am happy to share what I've captured if anyone wants to poke around themselves, but I think we're seeing enough of a positive change to call it a win, with the Google scenario being something a bit beyond our control and an independent factor in this equation.

1 Like