Documentation Workgroup meeting notes: August 1st 2022

franklin · August 3, 2022, 2:07pm

Attendees

Notes

The workgroup members introduced themselves, then went over the workgroup’s goals, membership, and communication according to the charter document.
Documentation workgroup meetings will occur bi-weekly on Mondays at 9am PST. The workgroup’s bi-weekly meetings will be open from now on (with the first open meeting on August 15th) and anyone can request to be invited by contacting @swift-documentation-workgroup.
Daniel: Do you see this workgroup’s discussions more as structured chat about specific features or rather open chats?
Franklin: I expect our initial discussions to be open, and after we have an idea of what we’d like to focus on, to have more structured discussions around specific features.
Ethan: Yes, it will be great for us to collaborate not only on tooling but also how to write great documentation.
Dave: Documentation has already come up in Swift on Server workgroup meetings so it will be good to align goals and collaborate.
Franklin: Over time, it will be great for us to drive a documentation culture within Swift.
Ethan: Yes, in a similar way to how API naming is sort of embedded in Swift development.
Dave: One of the reasons we added documentation to Swift Package Index is so that it becomes an expectation to write documentation.

The workgroup then had an open chat about how to improve the documentation experience in Swift. The notes below are organized by the topic that was discussed.

On the topic of documentation coverage:

Franklin: If you see that a project is well documented, you might be more likely to use the library.
Dave: Yes, and we can show metrics in Swift Package Index.
Victoria: Part of what can help more documentation is to make it super easy to write documentation. For example, in Rust, the documentation compiler ships in the toolchain so you can get started right away.
Ethan: There’s been a bit of friction in people adopting the Swift-DocC plugin because there’s still a manual step. Swift Package Index has been doing a great job at reducing friction remotely but it would be great to have this locally as well.
Sven: Is there a way to get documentation coverage?
Joe: There is experimental coverage in Swift-DocC. There are metrics to help you find out what has an abstract, code listings, etc.
Daniel: If we could get the documentation coverage infrastructure to work better, we could maybe boil things down to a single number so that you know right ahead whether the project is well documented.
Dave: Getting easy to understand metrics would be a fantastic idea.
David: The tooling could also help you guide what documentation you might want to improve next, step-by-step.
Kyle Murray: Metrics are good but they’re an incomplete quality indicator, for example writing documentation that’s not super useful.
Daniel: It could still be useful for contributors to use these metrics. But not something to follow to the letter.
Franklin: It might be nice to also view these metrics as you’re previewing your website, without requiring you to ask for the metrics.
Victoria: An analytical approach could help as well, where we highlight what APIs are referenced the most in other APIs.
Max: Swift community in general does a pretty good job at documenting, but since there was no clear standard before like in Rust or Go, people defaulted to writing Readme files. It would help a lot if the Swift toolchain or IDEs provided you with a default DocC landing page to encourage people to write docs.
Ethan: This is something I’ve been thinking about when designing the DocC Plugin. It would be nice if SwiftPM could accept templates from plugins.
Sven: It would be good to also be able to know whether a package has the base documentation template or whether the maintainer invested time in writing documentation.

On the topic of previewing documentation:

Kyle Ye: It would be nice to provide a way to live preview documentation.
Ethan: This is something I’ve been thinking about with the SwiftPM plugin. Currently the plugin doesn’t watch changes in your Swift source files. It would be great to have support in SwiftPM for that so that we can rebuild documentation automatically.
Daniel: It might be nice to provide a way for integrating this functionality in all IDEs.
Ethan: SourceKit doesn’t currently use DocC but if it did, it could help provide a live previewing feature.
Joe: On the topic of making it easy to write documentation, it’s difficult to remember how to write Info.plist files, which impacts the simplicity of generating, or previewing, documentation for your library.
Victoria: Yes, I think a docc init command to generate a template would be nice.
Franklin: It might be interesting to discuss how Info.plist should evolve, maybe it should be authored in a more authoring-friendly format.

On the topic of embedding code listing output into documentation:

Max: I’ve been thinking about the idea of embedding SwiftUI views into documentation, i.e., capture the output of a SwiftUI preview as a screenshot and inserting it in documentation.
Franklin: I’ve been thinking about that as well. It would be nice to also support capturing non-UI output, like print statements.
Kyle Ye: Swift Snippets might be useful to use here.
Franklin: Yes, I think Snippets make sense as an underlying technology that evaluated code listings would be built on top of.
Victoria: An integrated playground experience in documentation would be really awesome.
Franklin: Max, did you see this experience on the web as well?
Max: Yes, I think it would be really great to have on the web.
Joe: The implementation of https://swiftfiddle.com uses remote code execution to provide that web-first swift REPL experience.
Dave: It will be really important to keep parity between the web and native experiences.
Max: Yes, I fully agree, web should be the main interface.
Franklin: Agreed, it’s super important to have a good web experience, and there are also benefits to running things locally. For example, if you’d like to use a locally-built toolchain with a new API you added to build documentation.
Dave: We’re running into similar issues like that with Swift Package Index where we need to upgrade tooling to keep up with swift-tools-version requirements.
Franklin: It would be interesting to see how the community’s usage of Snippets evolves and see how we can best integrate that in documentation.

On the topic of linking to documentation outside your DocC catalog:

David: I’ve been working on supporting linking between documentation. From an educational perspective, it helps with curiosity, find new APIs.
Ethan: Leads to virtuous cycle – makes documenting a package that depends on Package X easier while encouraging Package X developer to improve their documentation.
Daniel: Integrate this into swift package preview-documentation where preview site automatically produces documentation for all of your dependencies and serves them together
Max: Linking to external dependencies would likely also need robust versioning infrastructure to avoid breaking links.
Kyle Ye: Do we need a central site to host them?
Ethan: This infrastructure should not require a central site. DocC catalogs would vend a canonical base URL informing dependencies where they are hosted.
Franklin: We could also implement link resolution by including a link manifest in DocC archives that DocC would download ahead of the compilation, similar to how SwiftPM clones dependencies ahead of the build.
Max: To help with resolving links to other packages, it would be good to have a solid versioning story to make sure links don’t unexpectedly stop working.

On the topic of multi-platform docs:

Sven: It would be good to avoid introducing the platform in the versioning scheme and instead producing documentation for all platforms at once.
David: Multi-platform support is something that DocC has but none of the integrations like Xcode and SwiftPM use that at the moment.
Ethan: This would be great to discuss in the forums, to go over how you can set up DocC for multi-platform building manually.