Swift Website Workgroup Meeting Notes - 28th June 2022

My apologies for these being very late.


  • Dave Verwer
  • James Dempsey
  • Kristina Fox
  • Mishal Shah
  • Paul Hudson
  • Reda Lemeden
  • Tim Condon
  • Tom Doron


  • :white_check_mark: Done
  • :arrow_right: Ongoing
  • :a: Action Item

Previous Action Items

:arrow_right: Blog post review process by @TimTr and @tomerd

  • @tomerd described the process of using a gist for the entire review of a post to be difficult. Instead he suggested the following phases for the golden path:

    • Send post to Apple Marketing via gist as read-only
    • Get Apple Marketing approval
    • Make the post a PR for review, feedback, and iteration
  • @tomerd If Apple has larger issues with the post, resolve issues via email.

  • @tomerd If there is a secret blog post, Apple internally goes through their process and we receive a PR of the finished post to merge.

  • @daveverwer The community-sourced blog post about Swift WWDC announcements also found gist to be lacking some key capabilities.

    • Gist can only be edited by the author, limiting for multi-author posts.
    • No way to make line by line comments.
  • @daveverwer One of the authors set up a private repo and added the post as a PR to allow line by line comments. Ideally want a collaborative markdown editor.

  • @Paul_Hudson has successfully used Pages for collaboration which includes line by line comments, multi-author editing, and native app or web-based access. In his use case, they were writing Markdown text in Pages, even though Pages does not natively support Markdown.

:arrow_right: Progress towards preview deployments by @mschinis and @mishal_shah

  • @mschinis was not present so there were no updates on these previous action items:

    • :a: @mschinis to continue to investigate the preview process and whether there are solutions to the two issues from above.
    • :a: @mschinis to look into whether Netlify may be able to build a future Swift-based version of the site.
  • :a: @mishal_shah reported he is having internal discussions and continues to look into funding the project

:arrow_right: Adding more verification to the deployment process from @mishal_shah

  • :a: @mishal_shah will create an issue on the forum to gather ideas on what else could be tested.

:arrow_right: New homepage and navigation design investigation from @kaishin

  • :a: @TimTr to set up a meeting between @kaishin, @TimTr, and some other people from Apple regarding design resources.

  • @kaishin has posted some ideas about both navigation and a redesigned home page in a thread in the private forum which has generated some discussion.

  • @kaishin has begun prototyping in code and would like the group to talk about where layout/design prototypes should be posted and how private or public the prototypes should be.

  • @tomerd mentioned that it is great to begin moving forward with prototyping without waiting for the Apple resources

  • @tomerd suggested a private or personal repo to share with the group, but overall favors being more open

  • @mishal_shah also favors having this be open so that people can see the progress, get an idea of the approach the design is going with and provide feedback

  • Responding to a question from @0xTim, @kaishin said the prototype will be a full Jekyll site, likely with different branches representing different designs

  • @0xTim also believed being more public was a good idea, with a thread and link in the public workgroup area

  • @Paul_Hudson cautioned against getting feedback on a prototype that might promise new elements in a site that we would not be able to deliver, setting expectations that could not be met.

  • @daveverwer wondered if we should be thinking about what content should be on the home page before beginning down the road of designing what a new home page would be.

  • @kaishin said he thought that there is a chance some part of the design would be wrong in the prototype, but that work on the content would happen in parallel and the design could adjust accordingly. But in the meantime, with the prototype process a design system is developed with different page components that could be used by different types of content.

  • @James_Dempsey notes that a fair number of content items would be expected to be found on a home page, such as "What is Swift?", "Getting Started", etc.

  • @Paul_Hudson likes the idea of developing components as long as the prototype does not make promises that can't be delivered.

  • @kaishin indicated the prototype would use content already present on the site.

  • @tomerd suggested possibly 'Lorem ipsum' content instead of real content if using real content would lead to unrealistic expectations.

  • @daveverwer wanted to make sure the prototype process wasn't locking us prematurely into defining exactly what the website will and won't contain.

  • @0xTim suggested that a benefit of having community support for particular design elements could help make the case to include those elements if they would otherwise receive pushback from Apple.

  • @kaishin was not comfortable with the first few iterations of the prototype being widely publicized and soliciting public feedback until a few rounds of more private feedback and refinement.

  • The consensus reached was that links to the initial prototype would not be widely announced, but available, with @daveverwer suggesting the link be included in the meeting notes, when it is available.

  • :a: @kaishin to work on a site design prototype which will be available publicly, but feedback will not be widely solicited to begin with.

:arrow_right: Dynamic content proposal @James_Dempsey

  • @James_Dempsey asked if the site had the ability to schedule content with a thought of queuing up content to appear regularly.

  • @tomerd said that the site currently regenerates only when content is pushed.

  • @tomerd suggested scheduling the appearance of content by including the release date in the item's front matter and not generating items in the future.

  • @mishal_shah indicated that a cron job is available to us to periodically regenerate the site automatically

  • :a: @James_Dempsey to continue to revise and refine the proposal.

The prototype Swift-based static website from @tomerd

  • @0xTim would like to contribute to @tomerd's prototype

  • @tomerd is happy to work the @0xTim on that

  • @tomerd the prototype is currently using Stencil for templating and Publish for static generation, but he is open to other solutions including the templating mechanism from Vapor.

  • @kaishin Asked what Publish helps us do that we can't do without it and asks because he found Publish to be very opinionated with how it hooks up to middleware

  • @tomerd feels that if something already exists in the Swift ecosystem we should celebrate it and improve it rather than inventing a new solution

  • @tomerd said he was able to make it work and he would rather first try proposing changes to the project to make it easier to integrate rather than create something new.

  • @tomerd also brought up considering other existing Swift static site generator projects instead.

:arrow_right: Find out of date URLs that point to the old swift-internals

  • @mishal_shah reports that the existing action item can be closed. Any out of date URLs found going forward can be reported as issues.

:arrow_right: Moving / adding Swift Server documentation to swift.org @tomerd

  • @tomerd Swift Server currently has a few pages on swift.org, there are a lot of links to things outside of the site, but now that the site is open source, can we start bringing in more server-side content?

  • @tomerd A question is whether we want to host more domain-specific documentation or just core items like the language itself and the standard library.

  • @tomerd And a more tactical question is where should domain-specific documentation go, do we want a lot of links to pages not in the nav bar?

  • @tomerd There are currently a dozen pages or more. More than can fit in the left nav bar.

  • @James_Dempsey asked what kind of content is it. API for a library? More general conceptual docs

  • @tomerd More overview, not for a particular library. How to compile, set up a Docker container, deploy to Heroku.

  • @0xTim Believes domain specific sections make sense and for now a single page on the site with links to the existing guides.

  • @mishal_shah believes this would be good in the documentation section as well as opposed to just Swift server, so everyone looking for documentation is aware of the content.

  • :a: @0xTim will do the first task of adding a single page with links to the existing guides.

:arrow_right: Blog post approval process

  • @James_Dempsey proposed collaborating on a blog post about Swift Generics with Holly Borla from the core team. Since time was running short in this meeting, James wanted consensus to move forward, but broader discussion over the approving blog posts was deferred until the next meeting.

  • @tomerd thought there should not be too high a bar for a blog post that was knowledge-sharing, as opposed to something promoting a commercial interest.

  • @Paul_Hudson brought up that people loved the WWDC22 video that Holly did on Swift generics and that possibly a blog post version of the talk would be useful.

  • @kristina brought up the recent post done by Diversity in Swift about property wrappers under the title "Exploring Swift" as a possible general title for technical posts that are more about exploring the language or have a bit more of a niche focus.

  • @mishal_shah mentioned that it would be great to have tags or categories for blog posts on the site, which would make it easier to search for different types of posts.

  • :a: @mishal_shah will submit an issue about adding tags for blog posts

  • The consensus was to proceed on the post James had proposed. The post isn't a workgroup action item and won't be tracked as such.

Discussions postponed until next meeting:

  • Talk about blog submission and approval process including the issues and questions brought up by @daveverwer.