Documentation Workgroup meeting: December 16th, 2024

Swift Documentation Workgroup Updates
1

The Documentation Workgroup will be holding its next meeting on Monday, December 16th, 2024 from 8:00am to 9:00am 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.

Please propose agenda items in this thread.

2

Meeting notes

  • Dave: Swift package index SEO. Looking to produce a sitemap with the pages with most human authored content.

    • Dave: Likely want to know not only what pages have abstracts, but also lots of paragraphs.
    • Dave: Starting with a small number of URLs and increasing would be a good way to approach it.
    • Sven: If this it done in DocC, need to be very specific about what data we’d like to know. “has abstract” vs “has human authored content”
    • Dave: Should explore different approaches. See if for popular packages, both small and large, how many symbols would captures. SwiftSyntax has potentially 80K URLs. Dropping down to about 500 via a heuristic would be great.
    • David: If you’re already enabling linkable entities, you can also look at indexable records, which has the abstract in plain text and also has the full text content of the entire page and the headings.
    • Sven found indexing-records.json for a SwiftSyntax target.
    • Sven: Need to merge indexing-records.json when combining targets’ docc archives.
    • Franklin: Does docc merge these files when using combined documentation support?
    • David: It combines some files, others are moved to subdirectories depending on what they’re used for.
    • Dave: For the search results summary, search engines use the descriptions, which DocC render fills in properly.
    • Franklin: Specification for indexing records JSON here: swift-docc/Sources/SwiftDocC/SwiftDocC.docc/Resources/IndexingRecords.spec.json at main · swiftlang/swift-docc · GitHub
    • David: FYI anchors are their own elements, so you may want to filter out on-page elements (via the location key) for sitemap. Only tutorials have “inPage” elements because each tutorial section is considered separate.

  • Franklin: Next meeting will be in the new year.

1 Like