Documentation Workgroup meeting: July 31st, 2023

Swift Documentation Workgroup Updates
1

The Documentation Workgroup will be holding its next meeting on Monday, July 31st, 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

  • Continued discussion on reducing archive sizes

Please propose any additional agenda items in this thread.

2

I have an agenda item that might be fun to talk about: local full-text filtering in DocC archives. It might be a tricky feature to add, but it's a really nice navigation tool once you have it, so it seems at least worth discussing its viability.

Just to start the conversation, I made a lo-fi demo of the Swift book (source) that leverages the Quick Nav UI (press the "/" key or "/" button). Look for something like "autoclosure", "reference cycle", or "if case", pick a result, and it'll jump you to it (except in Firefox).

2 Likes
3

Updating meeting link for anyone looking - previous expired: Cisco Webex Meetings

4

Meeting notes:

  • Dave: some documentation pages are less useful in a given documentation archive
    • for example, a package has 48K pages, probably not all of them useful
    • protocol inheritance not always useful
    • Daniel: maybe change the default to not emit by default
    • Dave: We should take a large package like SwiftSyntax and turn these symbols off
    • Ethan: We can open a PR on SwiftSyntax to pass a flag to in the SPI yaml.
    • Dave: Sitemap not the root issue, it’s more about usability
    • Ethan: This might become more of an issue with multi-target documentation with too many symbols
    • Dave: Already dealing with building for multiple targets in SPI
  • Kyle: Quick demo of an addition to quick nav that jumps to all text results: headings, code listings, article text, etc.
    • Joe: Thumbs up, interested in this topic and has lots of experience here and willing to help.
    • Dave: As people write more articles, text search becomes more valuable since most of the content is unavailable to quick nav aside from the titles.
    • David: DocC generates an index now, could be expanded to include other information like code listings. (https://github.com/apple/swift-docc/blob/main/Sources/SwiftDocC/SwiftDocC.docc/Resources/IndexingRecords.spec.json)
    • Kelvin: Is there any impact on page load times for this?
    • Kyle: Not page load necessarily, but it does load the full text. Could happen on page load or only when you first activate quick nav UI.
    • Sofia: Suggests SwiftUI as a potential good test case, since it’s big enough to introduce lag given the archive size.
    • Joe+Sofia: There are algorithms for certain types of indexing that could help with things like missing letters or typos in terms.
    • Ethan: Question of whether this lives in quick nav or is separate.
    • Joe: It could be useful to jump to header instead of directly to the matching text in some cases, or if it’s more technically feasible.
    • Kelvin+Dave: You could use search as a way to direct people to related frameworks, like searching on SwiftNIO and NIOHTTP. The reverse approach could also be possible.
    • Kyle: In general, there’s a tradeoff between local search in a single DocC archive and cross-archive search; the latter probably implies a server-side component as it reaches some scale.
    • Kyle: Will continue to look into this, especially since the response was pretty positive. Will track down some leads mentioned in this conversation and report back later.

(thank you Kyle for taking notes for the second topic!)

1 Like