Documentation Workgroup meeting: September 26th 2022

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:

  • the current status of the recent TSPL efforts
  • strategy for the major initiatives we'd like to drive this year
1 Like

Attendees: @daniel-grumberg, @daveverwer, @ronnqvist, @ethankusters, @franklin, @Joseph_Heck, @taylorswift, @Kyle-Ye, @finestructure, @QuietMisdreavus, @Alex_Martini, Mic Pringle, @sofiaromorales


Updates on DocC-based TSPL adoption

  • 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.

Symbol identity

  • 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 content at least.

Quick Navigation

  • 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.

Action items

  • @swift-documentation-workgroup: Think about how we’d like to contribute to the major initiatives we discussed in the last few weeks, which are:

    • Simplify the process to get started with writing and publishing documentation using Swift-DocC. A goal is to move towards a model where developers can generate documentation for their projects without needing to configure an additional plugin.
    • Expand the scope of Swift-DocC to support multi-target project configurations and long-form prose content. For packages that are composed of multiple libraries, the goal is to support publishing documentation for a package as a whole rather than each of its libraries individually.
    • Efforts towards replacing the existing TSPL publication pipeline with the contents of the new DocC-based repository.
    • Work towards defining guidelines for writing great documentation for the Swift language.
  • @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.

  • @krilnon: Continue work on publishing a staging version of TSPL.

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.