The Documentation Workgroup will be holding its next meeting on September 26th 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.
Meeting notes for this meeting will posted in this thread shortly after.
Is there a particular agenda for the Sep 26 meeting?
Looks like I'll be traveling during this week's meeting; see you all at the next one.
It would be great to discuss:
Attendees: @daniel-grumberg, @daveverwer, @ronnqvist, @ethankusters, @franklin, @Joseph_Heck, @taylorswift, @Kyle-Ye, @finestructure, @QuietMisdreavus, @Alex_Martini, Mic Pringle, @sofiaromorales
Alex: I put together a list of DocC âsoft blockersâ for the TSPL publication pipeline to be ready. For example offline support is not a hard blocker. List is on swift-book GitHub issues.
Alex: In the last week, I added PR and Issue templates for TSPL, as well as a Makefile.
Franklin: How much of this work could be brought for filing documentation improvements in other repos, whether theyâre documentation-focused or not?
Alex: These provide a good starting point and could be shared to other repos in the future.
Franklin: It could be interesting to emit these automatically as part of a âdocc initâ command as well, so that repos that contain documentation have templates to encourage filing issues for documentation.
Daniel: Would be nice, weâd also need to know what source code hosting service youâre using.
Kyle Ye: I noticed that there were DocC warnings emitted when building TSPL. Some of these are due to bugs in DocC, and some of them due to issues in the documentation content. I opened DocC PRs to fix the former, which reduced warnings to around 10-20 issues. There are still issues for incorrect links to H4 headings, for which DocC needs to add support. On the documentation content side, some chapters are missing abstracts, and thatâs already tracked by an issue. I also added support for a âwarnings as errorsâ mode for DocC that weâll be able to enable for TSPL once we fix all the warnings.
Kelvin: Out of curiosity, why does DocC emit warnings for links in abstracts?
David: Mostly historical reasons.
Alex: Historically, abstracts in Apple documentation donât include links.
Kelvin: That sounds like something we need to relax in DocC.
David: We can remove these warnings when not using the âemit-digest flag. But we need to keep it or fix DocC behavior when removing warning when using âemit-digest.
Ethan: I also landed new support in DocC for more flexibility in content.
Franklin: How can we use these improvements in TSPL?
Ethan: Can start adding icons for pages.
Franklin: Plan for documenting these new features?
Ethan: I added new infrastructure for adding new directives in the future. I plan to expand this to auto-generate symbol graphs for these directives.
Joe: Alex, I saw that automated code listing testing was on the list for nice improvements we can bring to TSPL.
Alex: Iâm interested in working with the community on making that feature happen. Including expected failures.
Ethan: Swift Snippets could help here.
Kelvin: Swift Snippets projects that are built using the Swift 5.6 toolchains cause the tooling to crash. Fixed in 5.7 though.
Sven: Can this be fixed earlier?
Ethan: This would be good to discuss in forums.
Franklin: Over the next 2 weeks, Iâd like for us to get a sense of what contributions areas each of us are most interested in.
Kelvin: Wanted to talk about symbol identity across versions of documentation.
Ethan: In DocC, the USR is the only identifier that uniquely identifies a symbol. I feel like this is a technical discussion that should be discussed in forums.
Kelvin: USRs arenât a complete notion of identity.
Ethan: Thatâs a great example of something we should resolve in forums.
Kelvin: This will come up when we discuss versioning and multi-target documentation.
Daniel: Forums sounds good, doesnât seem to be pressing for Swift.org content at least.
SofĂa: Things are going well with the Quick Navigation feature Iâve been working on.
SofĂa: Opened a PR to disable synthesized symbols in SwiftPM plugin.
Franklin: For Quick Navigation, it would be great to get the documentation workgroupâs overall thumbs up.
Ethan: I think we should definitely start with the documentation workgroup weighing on enabling large features, but not as a strict requirement at the moment until we can develop a process.
Franklin: Agreed, and this initial large feature can be a starting point to what questions weâd like answered before enabling a feature.
@swift-documentation-workgroup: Think about how weâd like to contribute to the major initiatives we discussed in the last few weeks, which are:
@swift-documentation-workgroup: Review the list of soft/hard blockers for TSPL that Alex put together: Issues · apple/swift-book · GitHub
@sofiaromorales: Prepare a feature enablement document for Quick Navigation.
Thanks for taking notes during this week's discussion, Franklin! Since there was a lot of detail moving by quickly, I'd like to add a little more of it here for the benefit of others reading the notes. The reason that Apple documentation doesn't include links in abstracts isn't because "we've always done it this way".
The style guidelines that we follow at Apple have very specific requirements for an abstract, to keep content consistent across multiple writers and over time, but also to provide a good user experience reading the documentation. In this discussion, it was mentioned that they don't allow code voice or links in an abstract.
Abstracts are displayed in many places, including navigation and Xcode help and the quickhelp panel that pops up during autocomplete. Although it's always possible to display a link when viewing the abstract as part of the docs for a specific symbol, we can't guarantee that these other places will even be able to display links. For example, how would I follow a link that showed up during autocomplete? Where should that link's destination be displayed?
These UX considerations are part of what motivates the Apple style guideline â in our style, an abstract needs to be able to stand on its own as a self-contained one-sentence summary of the symbol. Code voice generally is a problem because it means the abstract is referring to a parameter or another function. Links are a usually a problem because it suggests the reader needs to follow the link to fully understand the concept. Figures or code listings would be a problem, because many places that display an abstract aren't designed to display that kind of content.
In other approaches to documentation, used by other users of DocC, it might make sense to allow links in abstracts if that's consistent with the UX and style being adopted there.