The Documentation Workgroup will be holding its next meeting on September 12th 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
Discuss the evolution of TSPL and documentation tooling support for it
Meeting notes for this meeting will posted in this thread shortly after.
Alex provided an overview of TSPL, composed of âA Swift Tourâ, the guide, and the reference.
Alex: Offline reading experience and formal grammar would be great to have in TSPL using DocC. Will be great to have the workgroupâs help to get open-source TSPL published to Swift.org.
Kyle: It would be interesting to discuss what level of DocC features we rely on. For example, formal grammars might not be a mainstream DocC feature.
Alex: Maybe we can change TSPL to drive a more general navigation feature in DocC.
Kyle Murray: Lots of great opportunities there, for example in interactivity on the webpage.
Ethan: What are the blockers to adopt the open-source version of TSPL on Swift.org?
Kyle: This is up for discussion, for example ePub adoption might not be a blocker.
Alex: Testable code listings would be nice to have.
Daniel: Running code listings and capturing output would be nice too.
Franklin: On the community side, how can we as a workgroup encourage contributions to the project? How can we work with the Swift Mentorship program to bring new contributors to Swift through documentation?
Daniel: Different levels of contributions; typo fixes, new ways of teaching. Processes need to be suited to different contributions.
Ethan: Lots of content in the Swift book comes from new features that went through Evolution. This content could be derived from the evolution content. Need to create areas where new contributors can participate. A staging ground would be helpful, with draft content that can be iterated on, so that contributing to the Swift book doesnât seem like a huge task.
David: Regex and Concurreny documentation was created separately I think.
Alex: I like the idea of looking at structural vs. non-structural changes.
Ethan: Questions around what documentation belongs on Swift.org outside of the Swift book vs. in the Swift book, e.g., Swift on Server content. Need to work with the website workgroup.
Kyle: Spectrum of contributions. For example in a blog post, you wouldnât expect a code listing to keep compiling in a few years.
Franklin: Would be good to define user stories. For example, someone who was confused about a Swift feature, and would like to clarify the docs.
Kyle: Interesting questions around the level of knowledge assumed in the docs. For example, Swift book shouldnât cover general non-Swift-specific programming concepts.
Victoria: Easier it is to allow small changes, the broader the contributor base we can have.
Alex: Swift book currently expects some level of programming background.
Franklin: Maybe we can direct learners to appropriate resources to learn programming.
Daniel: Would be good to be upfront about expectations of the target audience and have documentation about it.
Victoria: Yes, like a Contributing file.
Kyle: Thereâs some of that in the Readme, but it needs to be improved.
Ethan: Canât prioritize ease of contributing over ease of reading the content. It might be nice to provide the ability to create quick âhow toâ articles, which could be linked from the Swift book. DocC could be adapted to support more unstructured content, more blog-style.
Franklin: There are questions around reviewing this content, this is some bar of quality expected on Swift.org.
SofĂa: Yes, this would be great to have for new contributors.
Ethan: On the scale of âstructurednessâ of content, Swift Forums is very low and Swift book is very high. Something in the middle would be great.
Max: In Kotlin docs, they have a section called Idioms thatâs open to contributions. Could serve as a staging area.
Franklin: Contributions of localizations could benefit from this as well. The general discussion around making contributions easier by making the content more unstructured is something we should pursue.
Ethan: Overview of the layout flexibility improvements I made in DocC. This started because I noticed that thereâs lots of content that has a lot of conceptual documentation, but doesnât fit within the Tutorials paradigm. Wanted something in between, more flexible. Customizing page kind, See Also, Topics sections, article icons, previous/next buttons, etc.
Franklin: How do you see TSPL adopting these new features?
Ethan: These features will land on the main branch soon. Main branch of the Swift Book can build using the nightly toolchain.
Franklin: Weâll need to communicate toolchain requirements for TSPL.
Ethan: Other layout improvements: row/column layouts, tabbed layouts, text size customization, video, image captions. Allows creating custom layouts that donât have to be baked into tooling.
Kyle: Can Video directives support audio description tracks?
Ethan: This should be feasible through the video format. Video directive also supports alt-text.
Ethan: Also added grid-based topics section that can have images. Will be great for top-level pages.
Franklin: Plans to publish DocC TSPL to a staging website, e.g., GitHub Pages?
Kyle: No plans at the moment. Need to make sure we donât publish at an authoritative-looking URL. Need to make it clear that itâs draft content. But something we should make happen.
Franklin: Can point to the GitHub repo to invite contributions.
SofĂa: Size of TSPL DocC Archive?
Kyle: Itâs not large, a few MB.
Kyle: Will create GitHub Issues to track this effort.
Action items
Kyle: Create GitHub issues to track publishing a staging version of TSPL, to easily preview latest changes / dogfood DocC features
Ethan: Prepare script to automate publication to staging GitHub Pages
SofĂa: Look into adding support for hiding DocC pages from search engine results.
I apologize for not being able to make this last meeting. Wanted to toss out there that I love Max's idea of an "idioms" section that's easy to contribute to from the community. In past languages, I found huge amount of value in sites that collected details like this, these days some of that being StackOverflow, but you've got to be brutally careful about vetting the answer - and that it's not severely outdated.
Which bring up the second thing: I think it's imperative to have some way to verify that code snippets in the TPSL and any other key learning material are continually correct over releases - which means there's a maintenance burden as swift evolves (especially with things like Swift 6 and some source-breaking changes on the horizon), but that goes doubly for the convenience areas of any idiomatic pattern/cookbook like sections that might be available on the side. To that end, I'd strongly recommend that any CI that publishes draft content to a URL (github pages, netlify, an S3 bucket, or whatever we choose to use) also checks snippets content and provides clear and easy to find failure messages if (really when) any snippets stop working as advertised.
Each listing in the book already has tests for compilation + expected output / expected errors. The format we used is bespoke to the book, so there might be some work to adopt and (potentially) expand snippets to handle an equivalent feature set.
There's also probably no particular action item for Ethan here; I looked at his script from swift-docc-plugin and it was easy enough to adapt for the book's repo.