# Documentation Workgroup meeting: September 11th, 2023

**URL:** <https://forums.swift.org/t/documentation-workgroup-meeting-september-11th-2023/67182>\
**Category:** Workgroup Updates\
**Created:** [September 8, 2023, 10:32am UTC](https://forums.swift.org/t/documentation-workgroup-meeting-september-11th-2023/67182 "2023-09-08T10:32:30Z")\
**Posts on this page:** 2\
**Page:** 1

<div class="post-metadata">

**Author:** ![franklin](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/franklin/32/17924_2.png) [@franklin](https://forums.swift.org/u/franklin)\
**Post date:** [September 8, 2023, 10:32am UTC](https://forums.swift.org/t/documentation-workgroup-meeting-september-11th-2023/67182/1 "2023-09-08T10:32:30Z")

</div>

The Documentation Workgroup will be holding its next meeting on Monday, September 11th, 2023 from 8:30am to 9:30am PT (or [see the time in your own timezone](https://www.timeanddate.com/worldclock/fixedtime.html?msg=Documentation%2BWorkgroup%2Bmeeting&iso=20230911T0830&p1=137&ah=1)).

This meeting will be **open** to anyone who wishes to contribute. If you wish to participate, please reach out to [@swift-documentation-workgroup](https://forums.swift.org/groups/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

- Reducing archive sizes

Please propose any additional agenda items in this thread.

---

<div class="post-metadata">

**Author:** ![franklin](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/franklin/32/17924_2.png) [@franklin](https://forums.swift.org/u/franklin)\
**Post date:** [October 9, 2023, 3:43pm UTC](https://forums.swift.org/t/documentation-workgroup-meeting-september-11th-2023/67182/2 "2023-10-09T15:43:58Z")

</div>

- Continued discussion on including synthesised symbols by default.
  - Sven: Enable skip synthesised symbols flags in SwiftSyntax for testing.
  - Ethan: SwiftSyntax team is okay for us to disable synthesised symbols.
  - Sven: Can open a PR for SwiftSyntax.
  - Ethan: What are the other largest frameworks? Maybe we want to disable their synthesised symbols as well as we’re thinking about the long term solution.
  - Sven: The Stream library.
  - Dave: Reduced number of pages by half.
  - Ethan: SwiftUI-based frameworks would get a win from enabling this.
  - Franklin: What are next steps for whether we want to exclude by default?
  - Sven/Dave: Would be in favour.
  - Ethan: Question is whether it should be synthesised symbols or inherited symbols that should be excluded. We should come up with counter-examples where this is worse.
  - Kyle Murray: Is this the change that would make Array empty for example?
  - Ethan: Yes. Maybe we want to instead automatically curate pages rather than synthesising them.
  - Alex: Not sure whether the preferred approach for standard library is to have specific documentation for synthesised symbols, or to traverse the protocol hierarchy’s documentation.
  - Ethan: Maybe we should consider how to make DocC such that the standard library isn’t a counter-example to how synthesised symbols are handled.
  - Sven: Was there another flag to try?
  - Ethan: Yes there is one for inherited docs but it’s not available through SwiftPM.
  - KyleYe: Does it mean Array and Dictionary use the same default implementation of Collection protocol requirements. But they use different curated docs?
  - Alex: Yes, the documentation gets inherited from the protocol.
  - David: Yes, even if the concrete type gets a custom specialisation.
  - Kyle Ye: Can you document a synthesised symbol?
  - David: Yes, you can via documentation extensions.
  - Alex: Would be quite a large effort to document each concrete type individually.
  - Kyle Murray: We could use a tab navigator to provide documentation for each concrete type in the protocol’s documentation. For example, specifically for code listings.
  - Ethan: Agreed, I’ve been thinking about featuring code listings more prominently and this should be considered.
  - David: Reminds me of a problem where when you curate a synthesised symbol, you lose context as to which protocol that symbol came from.
  - Kyle: [==(\_:\_:) | Apple Developer Documentation](https://developer.apple.com/documentation/corefoundation/cgfloat/3017356) here, we show a note regarding where the comment came from.
  - Ethan: I’ll take an action item around what information we can display on the page for contextualising where a symbol comes from.
  - David: what are the next steps regarding turning off synthesised symbols? Is it just gathering more examples?
  - Ethan: Getting feedback SwiftSyntax, looking at getting more relationship data on the page, and looking at more examples.
  - Franklin: Which packages should we try this on?
  - Sven: Can get us a list of the top 10 packages that have lots of pages, and I can take the top few percent.
  - Ethan: We mentioned in the past that archive size isn’t the only concern, we want to improve the UX.
  - David: Also a concern that we’d be losing inherited cross-package documentation when turning this off.
  - Ethan: That’s a great point, maybe we need cross-module linking.