Documentation Workgroup meeting: February 12th, 2024

franklin · 2024-02-09T09:29:59.801Z

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.

taylorswift · 2024-02-09T20:06:15.987Z

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

franklin · 2024-02-14T14:06:08.742Z

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.