Documentation Workgroup meeting: October 10th 2022

Swift Documentation Workgroup Updates
1

The Documentation Workgroup will be holding its next meeting on October 10th 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.

Agenda

  • Review TSPL blockers to completion DocC adoption
  • Status update for publishing a staging version of TSPL
  • Feature enablement for Quick Navigation
  • Resourcing for this year's initiatives
2 Likes
2

In addition to the above agenda, can we discuss the following issues at the meeting if we have time?

1 Like
3

seeing as October 10 is Columbus Day, would it be possible to move the meeting to the 11th?

4

Very sorry if the following words are offensive to you. But it would not make too much sense for people who are not in the America. Just as the Spring Festival may not have too much meaning for non-Chinese-speaking areas.

IMO, a good reason for changing/postponing the date is that most (eg. more than 1/2) members of SDWG are unable to participate in the current time.

1 Like
5

Meeting notes

Attendees: @franklin, @finestructure, @Kyle-Ye, @theMomax, @ethankusters, @ronnqvist, @QuietMisdreavus, @Alex_Martini, @sofiaromorales, @krilnon, @taylorswift

Agenda

  • Review TSPL blockers
  • Publishing staging TSPL
  • Feature enablement for quick nav and maybe extension support
  • Resourcing this year’s initiatives

TSPL Blockers

Alex: Needs to copy over to GH Issues, two milestones: full blockers to publishing, and second category with things that can be dealt with after transition.
Franklin: List of immediate blockers: - abstract to each of the chapter.
Alex: Started with this on Friday.
Franklin: If anyone wants to help with this, it is only a matter of adding a single line to the top of every article/chapter. This would be a great way for anyone in the community to get started with contributing documentation to the project.
Franklin: - remove see also directive
Alex: - remove eyebrow
Alex: We have GH issues for both of these
Franklin: This is also a relatively easy way to contribute, as it is a single contribution to just markdown content.
Franklin: Alex also mentioned redirects from the old website to the new website.
Alex: Need to figure out who is responsible for maintaining the website and liaise with them
Franklin: Yes this would be the Website Workgroup.
Alex: The other side of redirects, there are chapter level redirects and section level redirect. Today it seems fairly common for links to specific sections. Those section level links won’t work with the redirects because the anchors will be different when migrated to DocC. I think it has been proposed before to be able to specify custom anchors. This feels like not a blocker.
Kelvin: I think this is a big blocker, as we would lose loads of PageRank.
Kelvin: Imprecise redirects lead to a loss in Google’s PageRank.
Ethan: Not sure this is a super important issue. It seems like a very small loss of accuracy.
Kyle M: We might also want the ability to insert an anchor at an arbitrary location in the page.
Franklin: Last blocker is links to level 4 headers or lower, but this feels like a bugfix and common expectation, we should address this on the forums. To recap the 4 blockers are:

  • Remove automatically generated see also and eyebrows
  • Add abstracts for chapters
  • Sort out redirecting links from the old website to the new website
  • Ability to create links to 4th level or smaller headings.

Alex: Some of the code listings use 3 space indentation, as the old pipeline restandardized indentation before publishing. Making corrections to code listing indentation would be an easy fix for new contributors.
Franklin: Once we converge on the final list of blockers we should make a forum post about starter issues that would help us publish using DocC.
Franklin: Does anyone wants to do a status update on the forums about publishing.
Kyle and Alex volunteer to do a status update on the forums about publishing TSPL.
Kyle: Let’s not call them starter issues but something along the lines of opportunities to contribute.
Franklin: Do you think we could include the link to the staging website in that post?

Publishing staging TSPL

Kyle: I have a branch with something that contains 90% of what is needed for staging version of TSPL. Uses plugin published to GH pages.
Daniel G: Do we have something for preventing google from crawling?
SofĂ­a: We have a thing were we can add some metadata to the <HEAD> tag that would prevent this.
Ethan: This is fine to unblock us here, but we should formalize a proper feature/directive to make this easier.
Franklin: Let’s have a demo at the next workgroup meeting.

Feature enablement

SofĂ­a: Context about quick nav
Sofía: Opened a PR for the latest changes. Needs to ping Marina to land it into the main codebase. It won’t be on by default, some manual steps are still needed in the doccarchive. After a couple of weeks we should keep try to enable the feature flag by default. I checked the docc CLI tool and it doesn’t seem to affect performance. Who decides the enablement by default?
Franklin: The community as a whole will decide, we need a small document that explains and motivates why it is ready for enablement. Then the workgroup can sign off and provide the community an opportunity to provide feedback.
Franklin: We need a separate thread which will help segment the discussion and encourage people to try it out. Maybe we can integrate with Swift Package Index?
Sven: We need things in an actual swift release currently, maybe we should move to a model were we use a more recent Swift-DocC. In general though we can provide much broader testing.
Franklin: Once Sofia lands the changes, you will be able to download a full toolchain and either install the whole thing in staging or alter the build command to point to the right docc-render and docc. We are very interested in trying this for DocC projects. To be clear you enable this feature using a theme-settings.json in the package?
SofĂ­a: and set a flag in it to true.
Sven: We could inject this in a bunch of packages and batch test a bunch of packages, but let’s take this discussion offline.
Franklin: Max how are extensions?
Max: One PR left that needs review. The feature is basically complete. We then need to add the feature flag in the Swift-DocC plugin to streamline trying the feature out.
Daniel & Ethan: Dependency on landing a change in SwiftPM to expose the swift compiler flag to the plugin.

Resourcing this year’s initiatives

The workgroup and guests discussed what initiatives they’d like to help with this year. This was the breakdown:

  • Easier onboarding onto DocC: Ethan, Daniel, Max, SofĂ­a, Sven
  • Expand DocC to support multi-target configurations and long-form content: Daniel, David, Ethan, Kyle Murray, Kyle Ye, Sven, Victoria
  • Wrap up TSPL DocC adoption: Alex, Kyle Murray, Kyle Ye, Franklin
  • Defining guidelines for writing great documentation for Swift language: Alex, Kyle Murray, Franklin

Logistics

Franklin: We should discuss these topics regularly and talk about these 4 initiatives and smaller groups in the meetings as well as discussing what is happening in the community like GH issues we might have missed, and forums, or things like Kyle Y, adding links to our names on the main swift website. We should discuss also how to help contributors making new pitches to the community. We want a model were we are providing opportunities and support the community to propose new features and help them be successful.

4 Likes