Documentation Workgroup meeting: August 14th, 2023

Swift Documentation Workgroup Updates
1

The Documentation Workgroup will be holding its next meeting on Monday, August 14th, 2023 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

  • File name format for Windows support
  • Swift-DocC README changes
  • Reducing archive sizes

Please propose any additional agenda items in this thread.

2

Meeting notes

  • DocC file name on Windows
    • Characters in file names are not valid on Windows
    • Need a backwards compatible format
    • Saleem: There isn’t a great solution. Should be possible to make a translation within the renderer itself, but it needs to know it needs to do it. Maybe could use theme-settings.json.
    • Ethan: A similar problem come up before when we added the navigation sidebar to DocC, regarding backwards compatibility?
    • Franklin: metadata.json can contain version info, but would need to be queried before render JSON
    • Ethan: Could add a fallback mechanism that assumes that in most cases, you’re on the new archive version.
    • Max: Would it be sufficient to make a request only for the first request?
    • Sven: How would the renderer technically be decoupled from the archive?
    • David: Could go out of sync because the server is able to use the same renderer to host multiple archives that could be of different versions.
    • Sven: How large is the web app?
    • Ethan: Not large in comparison to the render JSON.
    • Saleem: About 1MB.
    • Sven: Maybe we should change the policy of how DocC gets deployed?
    • Franklin: Would need a migration period.
    • Ethan: Max’s suggestion is compelling.
    • Kelvin: Would this still be compatible GitHub Pages?
    • Arthur: It should work the same way.
    • David: Need to cache based on archive boundary rather than domain.
    • Max: Is it just based on the first path component?
    • David: Mostly, yes.
    • Ethan: It’s similar to how the index.json file gets shipped.
    • Max: For static file generation, isn’t the web URL and the file path the same?
    • Saleem: Correct. We wouldn’t need to be able to generate those files on Windows.
    • Ethan: We wouldn’t be support generating GitHub Pages compatible archives on Windows.
    • Saleem: Also, need to consider cross-platform use cases, where building and hosting can happen on different platforms. If you download a file that has a colon, it disappears.
    • Kyle Ye: Are there other solutions that don’t break the URLs at all?
    • Ethan: Do you consider it to be a breaking change if keep the web URL format?
    • Kyle Ye: No
    • Daniel: Could we set up redirect rules?
    • Saleem: Knowing to do that is the difficulty.
    • David: The problem is with backwards compatibility.
    • Alex: Why do we need to follow the same scheme on all platforms?
    • David: For portability.
    • Kelvin: Documentation is also platform specific.
    • Ethan: We’re in alignment about looking up a metadata file to know what file name encoding the archive is using. But it breaks GitHub pages. We need an action item to look more into that, how to not break it.
    • Max: Maybe we should consider percent encoding the file names and web URLs.
    • Action item: Check if server implementations support this translation (@eango)
  • Sofia: DocC README
    • There was confusion on how to get DocC running so updated the README. People were incorrectly building from source.
    • SofĂ­a provided a demo of the README changes she is suggesting, including a clearer instructions depending on your use case, as well as templates.
    • PR in Swift-DocC repo
    • Saleem: Love the idea for the template.
    • Ethan: Templates are great, have you also considered tooling integration so that it also fills in basic values for you based on your environment?
    • SofĂ­a: Yes, from the command-line.
    • Kyle Murray: A great direction to go. Is it a case where someone is directed to use the SwiftPM plugin but use the vanilla catalog template which requires a direct DocC invocation?
    • SofĂ­a: Will need to make that clear in the README.
    • Ethan: Concern that a template repo would become too visible, not everyone wants an article-only catalog.
    • Franklin: Will the template repo stay around if it’s integrated in the tooling?
    • SofĂ­a: Wouldn’t require much maintenance. But it’s a temporary thing.
    • SofĂ­a: I have an open pull request, will also communicate in forums.
2 Likes
3

FYI, I opened a forum topic to discuss the README improvements. Here is the link to it: Improvements to Swift-DocC README file

1 Like