Documentation Workgroup meeting: April 24th, 2023

Swift Documentation Workgroup Updates
1

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

1 Like
2

Meeting notes

Attendees

Notes

  • Max: Enabling Swift Extension support by default for 5.9

    • Victoria: In favor, I also implemented improvements to remove empty pages due to manual curation, which was my last concern. Also added an improvement to show what module an extension is apart of. There is a future improvement opportunity for showing what the parent type is as well.
    • Ethan: We would enable this in the DocC plugin
    • Max: Will open a PR to enable it, keep flag for disabling, and keep enabling flag for backwards compatibility.
    • Ethan: Agreed, there are a few cases where you might want to disable, e.g., when you have lots of synthesized symbols.
    • Victoria: Working on a flag to disable synthesized symbols completely as a separate improvement.

  • The workgroup then reviewed GSoC proposals relating to the documentation experience in Swift. The notes are redacted for the privacy of the participants.

  • KyleYe: Plan for supporting C based languages?

    • Ethan: I have a slow moving PR to support this, but specifically for single language C targets.
    • Franklin: How will this interact with C++ interop?
    • Ethan/Joe: Saw a post about this earlier today in the forums.
    • Joe: Symbol graph tool seems to work different for binary targets. Will look into it more.

  • Discussion around TSPL and supporting the 5.9 release.

  • Alex: Posted a pitch a few weeks ago, focusing on macros and parameter packs. documentation for other areas will come later
    • Franklin: Where do these get published?
    • Alex: Keeping to work on main. When we get close we’ll make a 5.9 branch.
    • Alex: When we release 5.9 it’ll be published on swift.org.
    • Franklin: do we need to publish multiple versions at the same time?
    • Alex: Not needed in our branching model since we mostly run on main.
    • Franklin: If I use a prior version of Swift, can I know what features are available to me?
    • Alex: Taken different approaches for that in the past. Published two books, one for current release and current beta. When we moved to Swift.org, we lost the ability to publish two books.
    • Kyle Ye: Should we add version support in DocC?
    • Ethan: TSPL would be a great use case for this. Also want to see what new pages were added, with diff support. Brings up questions of back maintenance. Have you considered tagging pages with the availability deprecation to indicate what version of Swift supports this feature?
    • Alex: Would work well for more isolated content like macros, but doesn’t work for new sections within a page.
    • David: Maybe we should bring availability attribute to sections.
    • Victoria: Yes, that could be attached to certain headings.
    • Franklin: Is there anything we want to do in the short term? Such as showing 5.9?
    • Alex: We don’t indicate very well today the current version.
    • Kyle: Having two versions is potentially good but haven’t received feedback about it being confusing.
    • Franklin: In the past we had a label for the version though.
    • Alex: Is there a good affordance that in DocC?
    • Ethan: Could add that at the top level page.
    • Alex: Linear learning path is useful, top level page is a good place to call that out.
    • Franklin: Do we need a version label?
    • James: I found it useful to have both the stable version and the beta version. Outlining changes is useful as well to avoid re-reading everything.
    • Ethan: My hesitancy with doing this now would be breaking existing features, but in the immediate term might be useful to publish at separate URLs.
    • Alex: Can you share more about what was useful about having both versions?
    • James: Sometimes you’re not working with the beta version and seeing wrong information throws you off. I download the eBooks to get docs for the version I’m on.
    • Joe: Good to get a sense jumping from the book and proposals. It helps having the beta version.
    • Franklin: Also in the Swift on Server community where you can’t necessarily upgrade as fast.
    • Joe: Would love to see beta published in parallel to Swift.org
    • Alex: If we do nothing, you’ll get the opposite, only the 5.9 documentation on swift.org. I think it would be difficult to argue that swift.org should only have the stable version.
    • James: Having 5.9 on swift.org would make sense
    • David: as a very short term solution, could we host both documentation on swift.org with different base paths?
    • Alex: That’s what we did historically
    • Franklin: Would the current URL be the current beta?
    • David: I think so.
    • Kyle Ye: Will we maintain the links permanently?
    • Ethan: GitHub pages approach might be good short term.
    • Alex: Showing version availability could be useful.
    • Ethan: Availability tag might be interesting.
    • Ethan: Custom header support could be an interesting short term workaround