The Documentation Workgroup will be holding its next meeting on August 29th 2022 from 9am to 10am PST.
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.
Agenda
Go over the tooling and process enhancements we've identified over the past few weeks, and start prioritizing them in terms of short/medium/long-term focus areas with a goal of sharing them with the community.
Meeting notes for this meeting will posted in this thread shortly after.
Feedback from various community sources (GH issues, forums, etc)
Franklin: Talk about doc coverage (what docs to write next), live previewing docs, embedding output of code listings in the docs, multitarget documentation and linking from one catalogue to another, documentation for multi-platform, docs diffing, how to have more contributors (maybe via an edit button), localization, documentation versioning, getting started with docs (swift package doc command), more long form content e.g. book like content. Everything from GH Issues is covered above.
Sofia: Mostly book-like content, and main one is one doc archive for multiple targets
Victoria: Swift Markdown, SymbolKit and swiftc. Not much of a theme, support more usages of symbolgraph and have everything in it.
Daniel: Multi-target/multi-framework and cross links is a topic that came up often in various forms in the forums. There is a clear appetite in the community for being able to document conceptual module/framework/target/package groups as a single logical entity. In general there are two categories of requests:
Requests about internal things like control of which symbols get exposed through docs and metrics about the process (coverage, warnings etc)
Externally visible things, page styling, new UI elements (on this page, symbol badges), diagraming support (mermaid)
Explicitly exclude symbols
Dave: Many new complaints about DocC archive size
Discussion
Franklin: We’ve been asked to draft some ideas of what we are working on for next year’s Swift release. Good opportunity to carve out scope and pick some features we should be working on short term. Let’s focus on impact over the next year to the Swift community as a whole.
Ethan: Let’s push forward on things that need cross functional OSS support, as opposed to smaller tooling improvements.
Joe: What has the most impact to me is cross-linking and multi-target docs. I feel like this is something that people hit frequently.
Franklin: New repos in the Swift.org project are moving to use DocC, things like SwiftNIO would benefit hugely from this because it is structured as many small packages.
Joe: From the highest level it allows you to reference things you depend upon and not be confined to your own code. It seems like without this it is a real blocker for adoption for many folks, and other tools support this already.
Franklin: Yes, the learning benefit here is that you can easily navigate across libraries.
Ethan: I see people get excited about DocC, specifically about putting together conceptual docs holistically. However, that breaks for things like SwiftNIO and others that have multiple packages which is something that we are trying to encourage.
Kyle Murray: This is happening even for the Swift standard library, e.g. Regex Builder.
Max: swift-async-algorithm does heavy linking to the standard library, which we should support.
Ethan: We are talking about three things: cross linking and multi-target and multi-package.
Franklin: I propose we stay generic and talk about the experience we are striving for in terms of linking everything together. Let’s not be exact about what we are doing, and just mention it to see if other people want to join the discussion. I think we are pretty convinced that is something we want to focus on this year.
Max: Should we look at frontend features to more balance workgroup bandwidth for feature work?
Franklin: We should pick impactful features and then worry about implementation. Were you thinking about something?
Max: Localization maybe?
Ethan Let’s look at stuff outside DocC, maybe getting started with documentation generation could aggregate more skills.
Ethan: We need a unified story for documentation generation which we don’t currently have.
Ethan: For tooling there is friction with adopting the plugin, we don’t want people to rely on docc in the toolchain in the same way you don’t manually invoke swiftc. Instead we should make the plugin part of the toolchain like in other languages e.g. Rust with cargo doc.
Franklin: This feels like a year-long effort. Let’s design the command line we want and then collaborate with SwiftPM contributors to figure out a path forward.
Ethan: I think that is right, and we should use this opportunity to revisit the CLI interface, e.g. there was feedback that the current plugin interface is too verbose.
Franklin: It would be nice to have easy commands for deployment etc. As part of that we need better documentation about getting started with docs and think about templating, like adding a template as part of swift init
Dave: In Swift package index this would make it easier for us.
Franklin: An end to end story is not complete without a publishing story and I think Swift Package Index would be an ideal candidate for that.
Sven: Maybe there is something to add, we (Swift Package Index) currently require a specific file to be written to generate documentation, maybe standardise this to make it usable for other tools.
Franklin: Evolving the package manifest to indicate that documentation is there might be a good idea.
Ethan: This would be needed for multi-target etc.
Daniel: Maybe the manifest is the place to expose information that we need for cross-package linking.
Franklin: The package manifest is a good place for this.
Marin: We need to be able to disable this, because some packages fail to generate symbol graphs, e.g. dependencies we don’t need docs for we should be able to hide it.
Ethan: Beyond if it’s broken, we need this to be able to hide things to better curate things conceptually.
Marin: This can really help with archive size. Often I would never be interested in some of these dependencies.
Franklin: Between cross-target and getting started there is a lot of scope for collaboration with Swift PM folks.
Max: When we talk about multi-target documentation, we have to think about a consistent hosting story as well as building and versioning, e.t.c. We maybe don’t want to risk issues with unstable linking and the community feeling like the feature is “broken”.
Franklin We might need a notion similar to “ABI” stability for documentation content that could be made backwards compatible for this linking story. We need to think about linking issues like linking to docs hosted by other people to make this effort successful.
Franklin: So far the story is to expand the scope of doc tooling and to make more things documentable which I think is a good story so far.
Sofia: Maybe we also need to start thinking about archive size to avoid further bloat with the new features we are going to push.
Ethan: That feels like a bug fix and should not be part of the workgroup, but maybe I am wrong.
Franklin: In my mind this is a pillar of our effort, and the size component fits well there, e.g. we want to make it easily hostable ergo it should be small etc.
Ethan: Should we invest in CI to make sure archive size stays manageable?
Ethan: With what we talked about I feel like long form content and documentation for extension to external types fits well within that.
Franklin: Sounds great. What use cases did you have in mind for long-form content?
Ethan: There are many big things in the community that could use this, e.g. TSPL, Vapor, and others.
Franklin: Will this benefit the community from an authoring or reading perspective?
Ethan: Not so much authoring for most projects but the few projects that would need it are read by many.
Ethan: Fits the cohesive ecosystem story to make all documentation contents have a single home and one clear path to writing great docs for swift regardless of the type of docs we are writing.
Franklin: Do you see long form as API reference of more standalone narrative docs?
Ethan: More standalone. I think there are a few things that could use this to improve the process for contributing to docs, which makes it collaborative for these large collections of content.
Kyle Murray: Maybe useful for manifestos that are published for Swift Evolution that need to be linked back to? Maybe this is a good use case for long form content.
Franklin: Is this a new topic? As in how can we support the swift evolution process with documentation?
Dave: We currently have articles in DocC. Articles feel like they live as a node within the API reference documentation as opposed to being the main focus, which is something the long form content proposal would be a better fit for.
Daniel: Long form content tooling being the same as reference docs is a good thing to allow the community to contribute back to these conceptual big pieces with familiar tools as opposed to having to learn a new tooling ecosystem for these longer pieces.
Marin: The whole thing feels extracted from TSPL, and that the scope is too narrow as a result. And that we should figure out more use cases to really hone in on the features that are actually useful. Since this a completely new direction for the tooling maybe we want more confidence in it being what we want.
Ethan: I wasn’t thinking about TSPL that much when I proposed it, the goal was to create more tooling to allow people to do more general things in DocC. Those proposals are just one piece of it and there should definitely be more.
Franklin: To recap so far, I think this is a pretty neat story, making it easy for people to start writing documentation, and enable more use cases for reference documentation as well as enabling wider use cases with longer form content. Is there more stuff we want to bring out to the community that isn’t part of tooling?
Daniel: Guidelines for contributing to documentation and helpful tips for new starters to contribute.
Alex: Make it easier for people to use PRs that would automatically link back to the guidelines and show documentation diffs.
Franklin: Seems like a multi-year effort, we should discuss with the community what it means to write great docs. This year maybe we start with the Swift standard library and start with questions like “How do I get started fixing existing docs?”, “How do I add new docs?”. This helps with diversity efforts to get people started in the swift project by creating docs before maybe graduating onwards. We can then generalize this from the swift standard library to the entire Swift project.
Sofia: This ties into templates and maybe integrating this with the templates.
Franklin: Some automation around defining rules about content and automatically checking them within DocC?
Ethan: We don’t have a story around docs diffing and we might need to see when Swift 6 is planned to see if we can align with it?
Franklin: We need to figure out what the plans are for the package format stability before looking at that sort of work.
Action items for next week
Franklin to draft a few paragraphs about the workgroup’s direction for the next year, and iterate on it with the workgroup.