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

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.

Code examples with up-to-date APIs. That is the biggest problem with StackOverflow. You kinda have to assume the APIs are outdated but the underlying idea is accurate.

5 Likes

In a different thread, Ben mentioned compiling a collection of algorithms that are desirable additions to Swift, but still need discussions and proposals to work out the details. Creating and promoting this list on swift.org could help encourage a lower sugar/higher protein evolution diet :)

3 Likes

First thing I can think of is a documentation section. Hopefully something better organised than what we currently have on the developer website (Apple Developer Documentation). I'm thinking something more like https://swiftdoc.org, but less automatic and more manually crafted.
I just saw that the excellent language guide made it to swift.org (The Basics — The Swift Programming Language (Swift 5.7)), although it could be more prominently featured and misses and advanced section (mostly regarding generics).

2 Likes

"Why Swift for X" documents, similar to Why Swift For Tensorflow.
As we try to push adoption of Swift into new domains (systems programming, backend development) it would be nice to have some robust arguments for why you would use Swift in those domains, as well as highlighting some of the tradeoffs and why they are good tradeoffs or how they may be addressed by future Swift features. Finally, having some callouts like "here is a company building a sophisticated web application with Swift" would also be helpful.

9 Likes

@tkremenek! Swift is a great language, and I'm loving it!

  1. More articles about the internals, reasons why, or updates to the language:

    1. Dictionary and Set Improvements in Swift 4.0 @nnnnnnnn
    2. Objective-C id as Swift Any
    3. The Swift Evolution proposals are sometimes a bit dense, and a more beginner friendly article on a change, why it matters, how it helps move the language forward would be nice.
  2. There's a disconnect with the Swift Blog from the developer site. No updates since Oct 12th 2016.

    1. Accessed from: Swift - Apple Developer
  3. Swift Evolution dashboard should definitely be linked!

  4. Can you feature community educational content?

    1. I want to create more training resources for Swift, so featuring community content would be nice.
    2. The hardest part is that you keep changing the tools, UI, and language which makes it hard to do videos + articles.
  5. One big challenge on StackOverflow is that there's so much content for Swift 1, 2, 3, 4, and Objective-C, so for beginners it's really hard to know what code is up-to-date. Most of it isn't, so it's this dance you have to play when you're trying to get code to work.

Semi-related: Apple Documentation

  1. I find the new Swift documentation confusing with all the clicking I have to do.
    1. Compared to the guides which I could read linearly, now I have to drill in and out of the documentation to figure out how to do something
  2. Search on developer.apple.com is bad, it's easier for me to find things searching Google

Thanks!

3 Likes

As a newcomer, I totally agree with this point. A paths of gradually deepening into subject links - to documentation and tutorials, maybe divided into topics, but finally wrapping it all as a whole - would be a great help getting into Swift and the infrastructure. In other words, it would be cool to have one starting point, then diverging paths showing how to act in Swift World, finally getting into one point again, saying something like: "Congrats, now you're prepared to live in this world" :smile:

3 Likes

Idea: Start with a focus on things that help people to contribute.

1 Like

Thank you very much for opening this question up for community feedback. I think that documentation, sample code, and getting started tutorials would be a valuable addition to Swift.org. I think this would help new developers get started and expose them to the wider ecosystem that Swift encompasses outside of just iOS development.

Thank you for everyone's terrific feedback here. I need to sort through these and incorporate them into an aggregate plan, but this input has been immensely helpful.

10 Likes

I've been making an online Swift playground long before IBM Swift Sandbox. I name it WebSwift, you may try it here. Well, its look isn't as fancy as IBM's, but it works and it accepts input. Just updated it to Swift v.4.1.3 a few days ago.

About the swift.org site, here's my suggestions…

  • Official swift online playground that is written in Swift too, at least the backend part.
  • Better "Get Started" section to help new comers (like me) but don't too focus only on XCode and iOS. Please, also add support for Linux and MacOS users as well.
  • Better documentation, obviously. But please add more examples and working demoes.
  • Project gallery as show case for great third party projects that are written in Swift.
  • Community contributed wiki pages. It has to be moderated to make sure each page has correct and updated informations.

I think that's enough for now.

4 Likes

And that's definitely great! Is the kind of thing that the community should do without waiting for an official answer. :smiley:

That said, my hopes is that having an official Swift Online Playground we could see more contributions from the community and maybe even a hook into the CI to be able to try snapshots online, or even builds from a pending PR to be able to offer better feedback in an evolution proposal.

2 Likes

I really like the spirit behind the events section idea. I love the idea of being able to make Swift.org a place for swift users to organize to meet in the real world.

2 Likes