August 15, 2022: Documentation Workgroup Meeting Notes

Attendees: Bina Maniar, @daniel-grumberg, @daveverwer, @ethankusters, @finestructure, @franklin, @Joseph_Heck, @krilnon, @Kyle-Ye, @QuietMisdreavus, @ronnqvist, @sofiaromorales, @taylorswift, @theMomax

Action items

  • @franklin to collect high-level feedback from Swift-DocC GitHub Issues to aid in feature planning at the next meeting
  • @sofiaromorales to do the same for Swift-DocC-Render
  • @QuietMisdreavus to do the same for Swift-Markdown and SymbolKit
  • @daniel-grumberg to do the same in the Swift-DocC section of the Swift Forums


General updates:

  • @finestructure: SPI has added a version dropdown support that effectively allows for switching between different versions of your published Swift-DocC documentation. Supports up to three versions in the UI.
  • @daveverwer: In some cases, SPI will show more versions. SPI will always show the latest major version of each release moving forward.
  • @taylorswift: Is there concern with supporting versions of documentation moving forward as toolchains evolve?
  • @finestructure: Our strategy is to save the DocC archive output from each build and never touch it. This ensures link stability moving forward.

Documentation diffing:

  • @franklin: Let’s focus on higher-level documentation discussions. How could we support diffing moving forward?
  • @taylorswift: I’m interested in diffing Symbol Graphs to reduce data size requirements. However, it often isn’t possible to find a truly linear history with documentation repos.
  • @franklin: What are the benefits from a UX perspective? What would a developer like to see from a diff?
  • @daniel-grumberg: What’s interesting with diffing is the content: What APIs have changed between versions of the package? What has changed in the documentation content?
  • @taylorswift: I don’t think anyone is looking up documentation for specific versions of toolchains. More concerned about link stability- should be able to ensure that a page still exists even if the toolchain changes.
  • @ronnqvist: Would be interesting to explore how to generate manual migration documentation. Should there be a way to write extra markdown files that specify manual migration instructions?
  • @theMomax: Should diffing be API-only (symbol graph based)? Or should it include documentation content as well (articles)? I think this should likely be limited to only API diffing.
  • @franklin: Not sure I agree. I would be interested in any new articles that are added with a new version of a package. For example, Max just added a new article along with several new API to SymbolKit and adopters of SymbolKit would likely be interested in that as well.
  • @QuietMisdreavus Content diffs would also be interesting. For example, if a symbol adds a note callout instructing adopters to not use it moving forward it would be great to see that annotated in the diff.
  • @ethankusters Content diffing is tricky because for every example of a diff that a reader would be interested in, there’s a handful that a diff would not want to see.

Improving the process for contributing to existing documentation:

  • @Joseph_Heck One thing I’ve run into as an author is getting a list of the symbols up front so I can find out what to document. “I’m not familiar with this but I need to document this.” This is something we should make a little easier
  • @franklin: That goes well with the concept of a great “out-of-the-box” experience
  • @taylorswift: I’d like people to be able to go on swiftinit and modify the content directly on the website. This would then automatically open a PR.
  • @franklin: This would be great for OSS- if a reader sees a typo they can easily contribute a fix.
  • @daniel-grumberg: This is basically the Wikipedia model. Definitely value in supporting this.
  • @Joseph_Heck I’d like to be able to use this arbitrarily. Embed a link-to-source for a specific symbol anywhere. I.e: link to a symbol’s source code from a tutorial.
  • @franklin: Make it easy to contribute to documentation whether you own that content or not
  • @taylorswift: How would link-to-source affect stability of docs? This could introduce a lot of broken links.
  • @Kyle-Ye I disagree- you should be able to provide a specific link to GitHub source that will not break.
  • @daniel-grumberg: Depends on what you’re trying to achieve. Should edits go straight to the site or not? I think it’s reasonable for edits to go through review and wait for the next publication of documentation. Edits wouldn’t reflect immediately but would go out with the next release. This still greatly reduces friction: Doesn’t require cloning the repo, etc.
  • @QuietMisdreavus For the DocC-case specifically: Jumping to the docs location can get thorny because a symbol could be documented in markdown or in the doc comment.
  • @ronnqvist: Link would need to be specific based on what part of the document you’re editing. Diagnostics have the same issue.
  • @franklin: We’ve identified that we’d like to improve both the out-of-box experience for documenting your own package and for editing a third party’s documentation. The first one seems like something we should focus on sooner than later. Improve UX beyond what the Swift-DocC Plugin allows. Should be able to just download a toolchain and build documentation – similar to current Rust experience.

Localizing documentation:

  • @franklin: Kyle you mentioned you’re interested in integrating localization support into tooling. Can you expand on this?
  • @Kyle-Ye Should we follow the Apple standard or create a new one for the open source?
  • @franklin: Localization is really important for Swift’s diversity & inclusion goals. This could have a huge impact on Swift.
  • @daniel-grumberg: There is a big difference between localising an app and localising documentation. Apps are full of short strings- documentation is full of free-form prose. Would be interesting to allow contributors to provide their own translations of articles.
  • @taylorswift: On the forums, there is someone who has developed a documentation tool that supports multilingual documentation. We should loop them into future discussions here
  • @franklin: We should start a conversation in forums about localizations. Most of Swift’s documentation is in English – this is a huge barrier for people to get started with Swift.
  • @ronnqvist: What about the UX of reading partly-translated documentation? Maybe having great support for switching between languages would help a lot here.
  • @daniel-grumberg: I really agree with David here. There is a lot of longer content – but it’s unlikely that people will be willing to translate this expanded content. Folks might be interested in translating portions of a document but not the entire thing.
  • @franklin: Would be important to integrate with existing tooling like exliff. Some key pieces of documentation that the community will want to fully localise like the TSPL.
  • @Kyle-Ye The Swift on Server group is also investing heavily in documentation. Vapor provides at least three languages. They don’t use DocC- they use a separate repository for every language. When they migrate to DocC we should provide a better experience for localization.
  • @taylorswift: This is pretty linked to versioning. If you update the English version but fail to update the Russian version- do you still want to keep the out-of-date version around?
  • @franklin: How can we integrate localised content with non-localized content?
  • @Kyle-Ye I think this is a common problem. Common solution is to provide a comment specifying when the current translation was last updated and remind the reader that this content may be out of date.
  • @Joseph_Heck When I worked on the Kubernetes docs with localization, we identified a default language for the partial use case - (en) and showed that by default if a page/article wasn't available in the preferred translation.
  • @sofiaromorales: Most of the time when I read documentation the translation is out-of-date but it’s still great to have it available. We should maybe add warnings that a piece of translated documentation is out-of-date.
  • @daniel-grumberg: We’re focusing on the use case of using English as the primary language. There are certainly packages that have different languages as the primary one. We should not hard-code English as the default.
  • @ethankusters To this point: Maybe a first step on the journey to localization is just supporting other languages? Much of DocC is hard-coded to English currently.
  • @franklin: How much of this translation can be automated? UK/US translation
  • @Kyle-Ye genstrings

Wrapping up:

  • @franklin: Any other topics that people want to bring up?
  • @taylorswift: I think it’s great we’ve focused this discussion on end-user goals but I think that implementation-wise we need to collaborate more and think about how we’re going to deal with data storage of symbol graphs. We need to think about how we’re going to get there in addition to where we want to go.
  • @franklin: Much of these meetings will be focused on a more high-level and less of the implementation details. I would prefer if feature discussions on implementation discussions happen in forums so that everyone can participate.
  • @theMomax: Would it make sense to skim through the open issues on Swift-DocC in this meeting?
  • @franklin: This would be a good way to see if there are any priorities for the community that we’ve missed.
  • @franklin: Next week we will look over the issues that have come up in these two meetings and select what the group will focus on moving forward

cc @SDGGiesbrecht

Yes, that would be me. (But I will not write any more in an announcement thread.)

Just to clarify - we don't use separate repos anymore. All the translations live alongside each other, which makes it easier to keep things up to date (we use automations so any PRs that alter docs create a GH issue to ensure the translations are updated as well).

The tool we use is part of MKDocs and it generates translations for all pages that have it. If there's no translation available it falls back to the default language (in our case English). So in a folder you might have


Etc. That generates 4 language versions for the page. For the Dutch translations it just uses the English version so links still work and subsequent links go to translated pages etc

1 Like