Meeting Notes
Documentation Workgroup October 24th 2022
Attendees: @ethankusters, @daniel-grumberg, @krilnon, @Kyle-Ye, @theMomax, @finestructure, @Alex_Martini, @daveverwer, @ronnqvist
Agenda
- Status update for publishing a staging version of TSPL
- Status update on feature enablement for Quick Navigation (Sofia is not here today)
- Status update on Swift-DocC support for documenting extensions to other modules
- Determine initial action items for this year's initiatives
Update on publishing TSPL (Kyle and Alex)
Kyle showed demo of the staging environment of the TSPL book.
It looks like what the finished product will look like with a big yellow banner/disclaimer at the top of the page stating this is a staging version and not the real TSPL book. Currently, this is blocked by a bug fix in Swift-DocC to make the banner show up on all the pages and not just the top level page. Now with the new On This Page component we are at parity with the current version that uses the old publishing pipeline.
Can not add to the HEAD tag of the HTML we might need to solve this before or soon after shipping to avoid google indexing the site.
The staging site would be hosted under apple.github.io
Dave W: meta tag in the body might work fine, we could put a robots.txt in top level of the site domain. but that might not be possible. Let’s discuss this more offline.
Kyle M: Let’s talk about this offline possibly with Mishal who might know who controls robots.txt for the apple organization on Github.
Ethan: We should merge the Swift-DocC bug fix next week and sort out Google indexing. We should be able to publish the staging version by the next workgroup meeting.
Alex M: We still need to get the abstracts, and code indentation issues sorted before publishing the actual site though.
Ethan: We could look at using the new support for custom navigator icons to improve the visual style of the navigator.
Daniel & Ethan: Maybe have no icons for the actual pages and curate the individual chapters into the sections to make it more of a table of content. This feels like it shouldn’t be too much work?
Alex M: Have we talked about plugins to be able to add arbitrary syntax for a given book. Maybe a macro system, this would be extremely useful for things like the formal language grammar section of the book.
Ethan: Arbitrary functionality might be hard to implement, but a macro system sounds like it should be doable and useful for a wider audience.
Update on extensions
Max: Last PRs on swift compiler just awaiting review. Still need to add support in SwiftPM and the Swift-DocC plugin to make the support usable by the wider community. I think it could be done within the next 4 weeks.
Daniel to review swift compiler PRs during the week.
Daniel: We need to talk more about doing infrastructure to leverage Swift Package Index to do larger scale testing.
Sven: We are happy to look into this but need more details about what is technically needed.
Ethan: For extension support we would like to just try the feature for all packages and see what breaks, for quick navigation it’s more about having a special environment that people can try the feature for a few packages to see if people like it. It would require using a different version of swift-docc-render.
Sven: The infrastructure is not fully there but can be done manually.
Ethan: Let’s just focus on extension support here, for quick navigation we can just self-host a few packages (argument parser, TSPL, etc) for folks to try out.
Sven: We might want to do something more solid if this is something we want to do this often. Let’s discuss this offline.
Daniel: We might want to use TSPL for certain renderer features that we want to try out in a fully control, e.g. On This Page.
Update on initiatives
Easier onboarding for DocC and guidelines for documentation
Brainstorming about how to improve the onboarding experience.
Max: Giving people the chance of discovering DocC, if you don’t actively follow forums and/or WWDC the entire documentation ecosystem is not discoverable at all. We should make it more prominent in the swift command line and Swift Package Index. Doing more outreach would be amazing, but I don’t know what the right channels for that are.
Ethan: Having a contribute to this page feature has been done in Microsoft’s ecosystem quite successfully and feels like something that would work great for us, to make it more discoverable by just having readers of documentation be shown how to use the tools.
Sven: Is there a getting started with documentation page somewhere. Might be a good idea to link to a page that explains how to add documentation in Swift Package Index for pages of packages that don’t currently ship docs.
Ethan & Daniel: Consolidating docs into one cohesive place (instead of DocC docs, plugin docs, and Apple docs) would be a huge win to make it simpler. Maybe having a simple link to a get started with Swift-DocC page at the footer of the generated sites on an opt-in basis that would be on by default for things under the Swift umbrella and maybe in Swift Package Index.
Kyle Y: Making swift package init generate a catalogue by default would go a long way towards teaching people how to use Swift-DocC.
Ethan: I like the three pieces of integrating better in the toolchain, making it part of default Swift Package Manager workflows, and having centralized docs we can link to. They can be worked on in parallel, but the first two are blockers for the final piece.
Max: IDE support is a difficult but important thing. It’s hard right now partly because we don’t have specific support in SourceKit to make it usable in other IDEs, e.g. it’s very difficult to use without link autocompletion.
Ethan & Max: This is a big step and SourceKit might not be the right place for some of this. It might be a better task for next year but something we should keep an eye on unless someone is very interested in taking this on now.
Let’s make a post about improving user experience, both on the command line and making it part of Swift. It’s important to have this piece so it’s a cohesive story for the community. Let’s also integrate our efforts into creating guidelines for writing great documentation to make it a more cohesive and compelling story.
