Documentation Workgroup meeting: February 12th, 2024

Swift Documentation Workgroup Updates
1

The Documentation Workgroup will be holding its next meeting on Monday, February 9th, 2024 from 8:30am to 9:30am 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.

Agenda

  • Sven: Discuss rehosting documentation under alternative base URLs

Please propose any additional agenda items in this thread.

2

i think it’s worth discussing strategies for documenting nightly-only packages like the upcoming swift-testing.

2 Likes
3

Meetings notes

  • GSoC
    • Nominate projects on swift-website repo
  • Sven: Rehosting documentation under alternative base URLs
    • Sven: Currently URL structure is {owner}/{repo}/{ref}/documentation
    • Ref is version number
    • Google indexing is struggle because the URLs change often and SPI is being penalised
    • Proposed URL structure is {owner}/{repo}/documentation
    • Proposal is to not index the URLs with the version
    • Is there an easy way to re-host archives to different URLs?
    • Only difference is base path in index.html
    • Dianna: Stable URLs wasn’t helpful enough, still too many pages. 30% of pages got de-listed. enum cases is a big culprit
    • Dave: Correct that this is not the only problem, but a step in the right direction
    • Franklin: Would a server side redirect help?
    • Dave: Had a redirect until now, but not friendly with Google
    • Franklin: There is a docc process-archive command
    • Sven: Didn’t help much, top-level index.html wasn’t updated
    • Dave: Request gets proxied to S3
    • David: There is a feature where header can get injected to the top.
    • Franklin: Can use custom routing rules?
    • David: Documentation here: Documentation
    • Sven: What’s the point of the index.html files copied around?
    • David: For simple file server based solutions where you cannot set up redirects.
    • Franklin: Host and automate your DocC documentation - WWDC21 - Videos - Apple Developer
    • Dave: Google with penalise for a bunch of reasons
    • Dave: Another SEO issue: DocC Render only renders the direct children of the node. No crawlable links.
    • Dianna: Surprising because Google should be able to execute JavaScript.
    • David: The links in the sidebar are present in the content as well.
  • Dianna: Could SPI support nightly toolchains for swift-testing?
    • Vera: Immediate reaction is that there might be things in generated swift interface files cannot be parsed.
    • Sven: Jonathan reverted to use 5.9, documentation is working again.
    • Dianna: I wonder if this is a common thing that we will run into.
    • Vera: When macros were being built, it was nightly-only as well.
    • Sven: We support publishing nightly versions ahead of releases but not early enough to support swift-testing today.