RFC: making Swift.org a more valuable resource for the Swift community

The Swift.org website is meant to serve two purposes:

  1. Be the home page of the Swift language and the Swift community, and serving the general population of Swift users.

  2. Be a nexus for Swift as an open source project (i.e., the implementation of Swift itself), which spans multiple repositories on GitHub.

While there is some good material on the Swift.org website, what is currently there underserves both of the two goals mentioned above and there is a lot more that can be done. We are preparing to open up the Swift website for contributions from the broader Swift community, and as part of that I wanted to start a conversation on what the community felt we should do to make that website a better resource for everybody.

One example of how Swift.org could be a better resource is to provide good user documentation on using Swift on non-Apple platforms. Even basic "getting started" tutorials would be good to document, but there is a lot more we can do than that.

Another thing the website could do is pull more of the information related to the evolution process and the development of the compiler into the website proper instead of having it distributed across different GitHub repositories. Right now the evolution dashboard can only be found by going to github.com/apple/swift-evolution; there is no link from Swift.org.

I'm planting the seed for discussion here. I'm interested in what the rest of you think would be good to incorporate into Swift.org website, who are the populations it can better serve, how it can be better organized, etc.

Thanks in advance for your feedback.

34 Likes

I personally miss links to some documentation about:

  • inner workings of the compiler + some of the basics (basic overview, required formatting, etc.). As mentioned in the guide for Swift evolution, a working implementation is required for all proposals. For a person who comes "off the street", this can be very overwhelming. Yes, it is possible to read through the code and figure it out, but a general overview would be great and time-saving to many (in my opinion). Not sure how much this is possible without making this too much of a burden on the compiler maintainers.
  • general run-time information. It is hard to find information e.g. about how the witness tables exactly work. For me, this kind of information, as well as some more information about what the compiler is able to optimize is valuable. If I know that the compiler is able to optimize e.g. (wild guess) a filter into a lazy filter, I won't have to keep worrying about a performance about a simple filter(where:).

The stuff on the website is great start, it's great for a developer that wants to begin with Swift. But IMHO there is a lack of documentation in case you want to have a deeper understanding about what's under the hood.

I hope I haven't missed something that's already there. In such case, please, disregard this comment.

15 Likes

By now I have three suggestions:

  1. An Events section, where we can find Swift Conferences, Meetups and other activities that contribute to build this community, organized by dates and with an archive. This would contribute to the first purpose you mention.

  2. A Documentation section, were we can have documentation segregated by projects, levels, platforms and so on, build by the community itself. [should define this one a little more].

  3. [Maybe] Hold a "Changelog" inside each project.

11 Likes

I would suggest a projects section were people could 3rd party stuff, electively a searchable index. The projects would reference github rather than be a host. Hopefully in time it could be linked with SPM.

2 Likes

@hlovatt out of curiosity, are you imagining a package index on swift.org?

Two suggestions:

  • Download links for the latest stable release on all supported platforms (which might be a link to Xcode for macOS) should be on the homepage - people should be able to visit the site and get started immediately.

  • Swift.org should eventually host the documentation for the standard library and core projects rather than linking to Apple.com. Just in terms of optics, I think it’s important that Swift.org stands apart from Apple and for it not to seem like Apple has sole ownership of Swift – in other words, that Swift would continue if Apple were to decide tomorrow that Swift is no longer worth engineering resources (which I know won’t happen).

17 Likes

Yes, but more than a simple index. A place we’re you could advertise your project. It could be a simple repeat of the github 1st page. I am hoping that Swift.org would become the go-to destination when you are looking for Swift projects. Rather than github.

4 Likes

agree, there’s a whole lot of oral tradition that needs to be written down somewhere.

5 Likes

How about adding a wiki to swift.org and let the community build a Swift "encyclopedia".

2 Likes

Yes! A lot of valuable information is buried there that is hard to find. We need to make the existing resources and information more discoverable and accessible.

This needs real investment: Some key pillars of improving swift.org need focused investment with full-time staff, the community then can fill in the blanks, but it still needs a core editorial/steering team. This raises the question of funding, which circles us back to the other thread.

We've made some progress on the second one... The Swift Programming Language documentation is now hosted at docs.swift.org instead of Apple.com.

2 Likes

i think they meant the API docs

Also i know none of us are web designers but that font just hurts to read i’m sorry

A lot of programming language websites have some kind of online playground site (e.g., https://play.rust-lang.org/, https://play.golang.org/, https://try.kotlinlang.org/). Now that the IBM Swift Sandbox is dead, I would love to see some kind of Online Swift Playground.

30 Likes

Yeah, that would be really nice to have. There is amazing Rust By Example section where you can run code samples while learning Rust. I think Swift.org should borrow it)

3 Likes

Online playground would be nice.

Just a side thought, but it would be also interesting if GitHub's Gist functionality could be extended with collaboration of the Swift community and GitHub to accept Playground projects. If Playground would exist on Swift.org then it would be quite handy to be able to run a Swift gists on GitHub which would use Swift.org's playground functionality.


More availability of snapshots for different platforms directly on Swift.org would be nice (arm7 etc.).


Merging the functionality of SwiftDoc.org would be great. cc @mattt

4 Likes

I'd like to see all documentation related to cross-platform APIs (standard and core libraries) move to swift.org and kept up to date.

Dispatch is a painful example here. It's a core library but most of its API is undocumented. Other language's concurrency APIs have books written about them but we don't even have APIs docs :frowning:

14 Likes

I’m really glad to see a post like this to help the community :) I had a draft following up on my wishes for 2018 post, so I’m writing some bullet points here.

  • Better landing page with actionable call to actions: Right now the home page talks about what Swift is, but it would be more helpful to newcomers to get download links, getting started tutorials and links to be book and documentation.
  • If we had an official “Online Swift Playgrounds” it would be great to have a quick snippet of how swift looks like in the home page directly that allows people to play with the language straight away.
  • Prominent link to the Swift book: Right now is hard to see in documentation and I’ve had a couple of people asking me where to find it. I think is a great resource to learn the language so it would be nice to make it easier to find.
  • Easy access to Swift evolution information: the forums, current state of proposals etc. Basically make the evolution process more prominent to people.
  • I would love to see improvements on the contributing section, with links to community posts of people that is contributing code to the compiler or even to some explanations that right now are hidden in subfolders of the GitHub repo.
  • Community page: the community page right now is a little misleading. It talks more about the project managing structure than what usually is understood by “community”. For example the link to the forum is more important IMO that everything that comes before.
  • Community twitter: The community page should also point to the swift lang official social accounts. And those accounts should be more active and promote more about what’s going on on the community. Take a look at the Rust twitter account, it promotes packages, blogs, etc from the community all day long.
  • Community events: Events around the globe related to Swift would be a nice addition to a reworked community page.
  • Community projects: It would be great to have a page that promotes some more mature community projects, similar to the related projects category on the forums. Giving the ability to community maintainers of great projects be seen in the official swift.org page would help the community discover those projects and give more confidence on the ecosystem.
  • Package registry: I know that SPM is based on a non-centralized system, and that’s great! But I think is time to get a package registry in swift.org that shows new packages, most downloaded, recently updated, featured… etc. (see Rust’s crates.io)
  • Make it clear that this is bigger than Apple: I’m not sure how to pull this off but I think is really detrimental for Swift. People should stop treating Swift as something that only Apple controls and more about something that is open and owned by the community. “Influencers” (bloggers, podcasters… I”m looking at you) should stop mentioning Apple when talking about Swift, but maybe some better wording on the official site would help.
  • Linked to the previous point, move all the documentation to swift.org instead of having it in Apple developer site. Everything that is part of the open swift project should be in the swift page (language, foundation, stdlib…)
  • Add more working groups: maybe something we could take from Rust organisation and the way they’ve build multiple working groups to focus in different improvements. For example: community, documentation, other platforms, wasm, SPM…

Sorry for the long list but this is something that I've spend some time thinking about it :P

Thanks for opening this thread for discussion ^^

18 Likes

As others said, making it clear that Swift isn't only for Apple platforms seems important, this should be visible right from the homepage of swift.org. For this to be 100% true, the first requirement is probably to improve the dev experience on other platforms so that it is at least as good as it is for other popular languages as discussed in Crowdfunding world domination - #101 by tkremenek.

Making download links and documentation accessible right from the home page would probably have a good impact, in my opinion, many language users are expecting to be able to get started right away and any difficulty for doing that might lead them to think that using Swift anywhere outside of Apple platforms requires many hacks.

Highlighting the Swift community and generally showing all of the possibilities offered by Swift from the homepage would also be beneficial, why not with interactive and/or downloadable examples demonstrating the possibilities offered by third-party packages, the goal being to make a great first impression.

For the homepage layout, I would see a concise description of Swift, buttons for important actions such as "Download", "Documentation", "Contributing" etc... and below that why not :

  • Online Swift playground similar to what can be found on the homepage of other languages (see haskell.org or python.org), with a "random example" button enabling users to get a good preview of Swift.
  • News/editorial section with infinite scrolling (potentially subdivided into a few main categories) containing swift community news (major releases of packages, examples of using packages...), tips and tricks, Swift news (demonstrating new features when a new version comes out etc.)

Additional random ideas:

  • Translating the documentation/website
  • For potential contributors, a beginner guide to contributing to Swift, even for those without prior compiler project experience, would be great, why not detailed examples of fixing starter bugs ?
  • Guides for interesting possibilities of Swift on all platforms (eg: "Using Swift for server-side development", "Swift for machine learning")
  • If we identify common misconceptions made by Swift beginners, a section (maybe in the form of a FAQ) addressing those.
9 Likes

Hi Ted, thanks for kicking off this discussion, it's great to hear that the website is going to be revamped.

I think that technical documentation of the internals of the compiler etc. fits better in the source repos, alongside the code that it's closely associated with. That way we have a slightly better chance of it being kept up to date.

API documentation for swift.org deliverables (e.g. stdlib, Foundation, Dispatch) should be easily accessible at swift.org and ideally hosted there too.

I like the idea of a Swift conferences / events section that people could submit stuff to. There is so much going on I feel like I miss out on a lot of stuff because I'm not even aware of it.

Several people have mentioned an online playground - it would be great to link to http://online.swiftplayground.run/ for this.

I support the idea of a package registry, but this seems a more long-term goal, probably to come after SPM has a package index.

I came here to post basically this and Charlie has done a better job of explaining it.

I would love to see more in-depth internal documentation on how the compiler works.