Documentation Workgroup meeting: February 13th, 2023

Swift Documentation Workgroup Updates
1

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

Please propose any additional agenda items in this thread.

5 Likes
2

Some question on the second agenda:

  1. Will the channel be a private channel only for SDWG or a public one?
  2. Why we choose Slack as our platform instead of Discord or other platform? (Looks like Vapor community, SwiftPackageIndex community and many other swift-eco community all choose to live in Discord world instead of choosing Slack)
3

+1 agenda item on my end:

1 Like
4

Meeting notes

Attendees: @Kyle-Ye, @sofiaromorales, @QuietMisdreavus, @Alex_Martini, @franklin, @marinaaisa, @daniel-grumberg, @finestructure, @Joseph_Heck, @krilnon, @ronnqvist, @daveverwer

  • TSPL (Alex)
    • Approaching publication, just mechanics of publishing when next version of Swift goes out.
    • Draft page on GitHub Pages. What should the future of that page be? Could be a nightly build of Swift main. Could be also used as a draft branch to get the preview.
      • Joe: having it available for the main branch makes sense.
      • Franklin: For the second option, what does the PR workflow look like?
      • KyleM: Best of both worlds, where main is used for trunk, but we also build on PR?
      • Daniel: Can also build locally and attach to the PR.
      • Franklin: Also applicable for other repos that contain documentation.
      • Alex: Reviewing on main is difficult.
      • Daniel: main can represent the docs for next release. Good documentation for trunk toolchain users.
      • Victoria: Mimics Swift development.
      • Alex: Workflow that TSPL has used historically: main branch for next version of Swift. Content on main is ready to ship. Use release branch for small changes before the release.
      • Victoria: Release branch is cut later than Swift.
      • Alex: Similar workflow but release branch is merged.
      • Franklin: Would be beneficial for a consistent workflow.
      • Alex: Agreed but should consider whether this is the right choice for TSPL.
      • Alex: Maybe a middle ground where release branch gets merged back into main branch when it gets released.
      • Max: How does it work when you land work only for main and land changes only for release branch?
      • Sven: With frequent merges, reduce the likelihood of large conflicts.
      • Alex: On TSPL, work will likely happen on release branch as we’re converging for the work.
      • Victoria: Effectively main and release branch would become mirrors of each other.
      • KyleM: Can writeup a short post and discuss offline.
  • Slack channel for internal logistics communication (Dave)
    • Swift website workgroup has channel on Swift open source Slack.
    • Should channel be public or private?
    • David: Would be good to keep it public.
    • Daniel: Agreed.
    • Dave: Can create the channel for us.
  • Quick Navigation Preview (SofĂ­a/Marina):
    • Will be working on Quick Navigation Previews to show a preview of documentation in Quick Navigation. Aim for early March in terms of implementation.
    • Franklin: What’s the plan for communication with the community?
    • SofĂ­a: Will draft a pitch, same as Quick Navigation once we have mockups.
  • David:
    • Been working on link resolution improvements, to improve accuracy of link resolution and diagnostics. Currently disabled, wanted to discuss a plan for enablement.
    • Daniel: There is a mode for detecting mismatches between the old implementation of the link resolver with the new one. Maybe it makes sense to run the mismatch checker in SPI?
    • Max: If there are mismatches, isn’t that a bug?
    • David: There are a couple of cases where the new implementation is more correct. The old implementation sometimes double disambiguated. For Swift/ObjC APIs, there were differences in what parent type is used in the types.
    • Ethan: Only the latter will be non resolvable now right?
    • David: Yes.
    • Ethan: Since link resolution issues are warnings, they can be easy to miss.
    • Max: I wrote a bash script that downloads logs from SPI and finds issues when I tested extensions.
    • Sven: We could reuse this for this feature.
    • Franklin: What about issues where the reported mismatches are correct, i.e., the content needs to change?
    • Ethan: SPI will tell us how big of an issue this is.
    • David: There is a simple message we can grep for in the logs.
    • Sven: Getting a toolchain with the feature flag enabled that would help with testing.
    • David: Plan on communicating in the forums to explain the changes and timeline. Will do that once we have results from SPI. New implementation will be the default, old implementation will stay around for a year.
  • Synthesised symbols (SofĂ­a):
    • Been working on a PR to disable synthesised symbols.
    • When will this be released?
    • Ethan: Plugin doesn’t ship in the toolchain, it has its own release schedule. Will create a release a 1.2 that contains extensions support and synthesised symbols. In the future maybe we need a more formal process for cutting releases.
    • SofĂ­a: Sounds good. There was also discussion in Max’s PR about argument parsing. Are there planned efforts to make this better?
    • Ethan: Main constraint is that the plugin cannot add argument parser as a dependency.
    • Franklin: Should we disable synthesised symbols by default?
    • Victoria: I was looking into doing this in DocC.
    • Franklin: Do we need this in DocC if it’s in the plugin?
    • Victoria: This applies for protocol methods you implement as well.
    • Franklin: Continue discussion in OSS.
1 Like