Documentation Workgroup meeting: July 15th, 2024

Swift Documentation Workgroup Updates
1

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

Please propose agenda items in this thread.

1 Like
2

I cannot participate but I’ll throw in a couple things that have been bugging me, feel free to ignore any of the following.

I can’t seem to be able to produce documentation for C/C++ only packages.

A swift docs command that could avoid having to add the docc plugin would be very appreciated!

With interoperability being used and developed so much I think it could be good to tackle the multiple language support in docc-render and properly split C and C++ from Objective-C.

3

Please excuse my ignorance. I'm fairly new here. Is this about documentation generation (DocC) or about the documentation (the Swift Book) or both?

4

both DocC and TSPL are frequent subjects of discussion, among others as well.

1 Like
5

Thank you, @taylorswift.

6

Meeting notes

  • Action items from last week

    • Collaborative note taking: Sven compiled a list of pros/cons between platforms to take notes during meetings. Trying out Hackmd.
    • Collaborating with SwiftPM contributors: Franklin mentioned a good person to include relating to DocC x SwiftPM integrations is @Max_Desiatov, who we can include in future meetings to discuss integrations.
    • Workgroup membership: Franklin has started reaching out to folks regarding whether they wish to remain in the core documentation workgroup, or attend meetings less frequently instead.

  • David demoed new "combined documentation" mode in Swift-DocC plugin which allows combining documentation for different targets into a single DocC archives

    • David will post in forums in the coming weeks.
    • Unified sidebar navigator that shows documentation from all targets.
    • Can author documentation links to symbols in dependent targets. Cannot link to non-dependent targets.
    • David: Working on support for authoring custom landing page content (i.e., a top-level page) that conceptually describes a package at a higher-level. Can link to targets.
    • Dave: What tooling do you need to make this work?
    • David: Need a 6.0 version of DocC, DocC render, and the latest version of DocC plugin. Goal is to release this initial, in-progress, end-to-end support for 6.0.
    • Dave: Would love to adopt this in Swift Package Index.
    • Max: Looks great towards more unified documentation. Now you can follow links naturally. Can you link to transitive dependencies?
    • David: Can only link to dependencies that have been explicitly imported in code.
    • David: Have all the same capabilities for linking to articles in dependencies.
    • Max: Same syntax as linking to extension APIs?
    • David: Yes except that you need a leading slash.
    • Max: Where do extended types of a module you import go?
    • David: Still in the same place (in the extending module).
    • Max: Something to think about, whether we want to keep it that way or include the extension in the dependent target. Love this work.
    • David: My goal is to get this in people's hands soon.
    • Franklin: Any future directions?
    • David: Post an update and describe what's not implemented yet. Ask people to try it with enough pieces in place that it's usable.
    • Sofía: If you want to add a top-level page to describe the whole framework, how will that work?
    • David: You'd author a catalog for the package as a whole. Needs discussion in forums. Some folks have asked about using the Readme as the top-level page.
    • Franklin: Can you link to documentation in the standard library?
    • David: Not yet but something that I intend to support with the same syntax. Symbols in binary dependencies cannot be linked to yet.
    • Max: Does that mean that every DocC archive will contain documentation for the standard library?
    • David: No, there is a goal to not re-host dependencies' targets. In the future, DocC will turn the link to an absolute link of where that documentation is hosted.
    • Max: Some non-binary packages appear frequently as dependencies. It'd be nice to have finer grained control about what pages of the dependencies you want to publish.
    • Vera: Rustdoc supports specifying the absolute URL where documentation is published.
    • David: A bit tricky to know what one-off pages you'd need to include because they themselves can link to other pages.

  • Paris joins to discuss documentation on Swift.org

    • Paris: Been discussing heavy-lifting projects in website workgroup. There's been questions around documentation on swift.org that's not the swift-book. Information architecture revamping. Wanted to bring groups together to discuss. People have asked questions about documentation strategy as part of the move to the swiftlang GitHub organization.
    • James: Leading up the information architecture initiative in the website workgroup. We don't currently have a listing of all the documentation on swift.org. Intent is to move as much as possible to DocC. There's Markdown files, links out to WWDC, standard library documentation, Swift API guidelines. Grown ad-hoc for a number of years.
    • Paris: I call this 'community debt', like technical debt. On Swift.org - Documentation, unclear what the difference between Overview, Articles, etc. is.
    • Mishal: Swift infrastructure is set up to build DocC documentation. Main issue is that DocC doesn't have the ability to set up base URL prefix. It'd be great to set up a base URL for swift.org. Can we make DocC more native on Swift.org? Need to make documentation look more consistent. Navigation has been challenging as well, navigation bar is different in DocC websites.
    • Mishal: Would like to leverage docs.swift.org further. Want for example docs.swift.org/docc instead of docs.swift.org/documentation/docc.
    • Franklin: What would you expect the landing docs.swift.org page look like?
    • James: Needs definition. It's currently a redirect. Would be nice to have a sidebar with all the top-level pages of documentation.
    • Daniel: If all the content is DocC, then we could generate a sidebar.
    • David: You'd want to control what sub-pages of each documentation you'd like to see.
    • Mishal: We should come back with a proposal of what we'd like to see on the website.
    • James: Yes, agreed. Need to spend a bit time figuring out what we need from DocC.
    • Mishal: Would like insight from the documentation workgroup on insights on how to best structure information.
    • Paris: Shall we open our website workgroup meeting to documentation workgroup folks?
    • Mishal: I'm supportive of that. Would be nice to have one or two points of contact from the documentation workgroup.
    • Daniel: Also lean on Forums for those discussions.
    • Paris: Agreed. Confusing for someone new to know where to post your documentation-related questions/comments.
2 Likes