Improving the content on Swift.org

After Swift.org was open-sourced earlier this year, the Swift Website Workgroup (SWWG) began working on some initiatives to involve the community in the efforts to improve the Swift website.

On behalf of SWWG, I'm happy to share with you an initiative that focuses on making some immediate improvements to the content on Swift.org.

The website currently hosts some great content for visitors of different levels and backgrounds looking to learn more about Swift, but there's definitely room for improvement.

While a redesign of the website is necessary—and something we will involve the community in at a later point—it is a process that will take some time.

The goal of this initiative is instead to provide as much value as possible in the near future by updating the existing content on Swift.org, without making any bigger changes to the design.

SWWG has identified a few key pages where we think this effort would make the biggest impact, and have some thoughts on how these could be improved. This is not a strict plan, but rather a starting point for further discussions.

Home page (www.swift.org)

The current home page is very simple and does not provide much value. As it’s the first page that visitors see when they come to Swift.org, there’s a lot of potential here.

Some early ideas include adding a link to the latest version of Swift, a link to getting started, some information on why someone might want to use Swift, where and how Swift can be used, how to get involved in the many open source efforts, and showcasing what’s new in Swift and the community.

Getting Started (/getting-started)

At the moment, the Getting Started page contains a lot of information, and much of it is not necessarily required to get started with Swift. This can be a bit intimidating—especially for people new to Swift, which is the main target group for this page.

Instead, we would like this page to show new users how simple it is to get started with Swift and set up their first application. More advanced usage guides, like Using the LLDB Debugger, can be mentioned at the bottom of the page in a "Next steps" section, along with some other recommendations on how to continue learning and using Swift.

Download (/download)

The Download page currently hosts both different versions of Swift available to download as well as installation instructions.

One idea we have is to move the installation instructions to a separate "Install" page (/install). This page could also contain the download link to the latest stable version of Swift. That way, the Download page would only have to be accessed if you’re looking for a specific toolchain or Swift version.


As I mentioned before, these are just some of the ideas that the workgroup has discussed so far. We would love to hear your thoughts and ideas in this thread on how you think the content on Swift.org can be improved.

Once the work starts, a separate branch on the website repo will be used, and you're welcome to open pull requests there.

We're looking forward to your discussions and contributions! :slightly_smiling_face:

17 Likes

if i might offer a critique of the homepage...

Welcome to Swift.org

Welcome to the Swift community. Together we are working to build a programming language to empower everyone to turn their ideas into apps on any platform.

this is really vague and not really attractive to beginners deciding if they want to choose swift over rust. a new visitor is probably not coming to swift.org to contribute to the compiler or join the community or rush more swifties, they are coming to decide if they want to use a tool called swift.

Announced in 2014,

2014 was six years ago. in 2014 obama was president. what is swift doing in 2022?

the Swift programming language has quickly become one of the fastest growing languages in history.

this needs to come with a graph, or a link to a reputable source like the stack overflow developer survey.

For students, learning Swift has been a great introduction to modern programming concepts and best practices. And because it is open, their Swift skills will be able to be applied to an even broader range of platforms, from mobile devices to the desktop to the cloud.

not everyone is a student, and students are a poor choice of audience, because students usually don’t have much choice over what language they are using: they have to use whatever language the professor says to use. students also have no idea what “the cloud” is, that comes later with industry experience.

maybe rewrite this to be more targeted towards hobbyists and independent professionals, who are more likely to consider adopting a new language?

…sorry if this is harsh, but nothing ever improves without criticism. thank you guys for all your work on the website! i feel like it’s been really neglected for years now and i’m glad it’s getting the attention it deserves now.

12 Likes

Thank you for the feedback—and criticism (it is necessary and appreciated)! Yes, this text definitely needs a refresh (for anyone curious, have a look at the Wayback Machine to see when it was last updated :slightly_smiling_face:).

I think Rust's home page is a good example of the direction we have been thinking of in terms of content. A brief summary of what Swift is, followed by a few sections explaining why someone should consider choosing Swift, where and how it can be used, how to get involved in the many ongoing efforts, etc.

7 Likes

One thing that I think works well on the Rust website is that they show example code. Very small snippets, like this:

There's a lot to like about this:

  • Demonstrating some very common tasks; making a request to a server, handling a request.

  • It's small and easy to read.

  • It's code. This website is aimed at developers, after all!

  • Even if you don't understand Rust, just by looking at it, I'm sure all of us can decipher at least the broad strokes of what is going on. It looks very similar to Swift, Javascript, and most other languages with a C-like syntax.

    That's great! It immediately makes Rust feel familiar. I haven't read a single tutorial yet, and I'm already reading Rust code.

  • It mentions libraries such as Reqwest and Rocket, and directs me to places where I can find more information about them, to continue my journey discovering Rust.

    I worry that we worry too much (:slight_smile:) about "picking winners", and that it can be detrimental to beginners who just want to get started playing around with something. For them, I think it is worth prominently mentioning large server frameworks (such as Vapor) directly. Sure, other frameworks exist, and developers can discover those later as they become more familiar with the language - but for their initial introduction, we should focus on making it easy for them to get started. The biggest packages are the places where they're likely to get the most support - from the community or the maintainers themselves.

    As long as it isn't all Apple packages, mind; we do have a community and it's good to emphasise that. Lots of developers may be distrusting of an ecosystem which is overly reliant on Apple.

    Along similar lines, I think we should consider links to swiftpackageindex.com. Again, it's not an official part of the project, but it's a great community resource and a good place for beginners to browse as they begin their Swift journeys. Picking winners is the least of our concerns, IMO. It's a luxury problem.

12 Likes

Showing a code sample on the landing page is a pattern we're definitely looking forward to trying out in a later iteration. There are some challenging aspects typically associated with code samples but those can be worked out. For instance, if the example seems too contrived, it might fail to fulfill its purpose. Same might apply if it's too narrow of a use case, too intricate to understand at a glance, etc.

1 Like

Is there any reason the whole page needs to fit into the left 1/3 of my screen? I understand that columns can only be so wide, but we could centre the content, make it a little friendlier to read?

As I mentioned in the first post, there are definitely improvements needed to the design as well, but this is a bigger initiative that will take some time. In the meantime, we hope to be able to make some quick wins by updating the content.

This is one of the things that we probably would wait with until a redesign of the website happens, but it's still great feedback. :slightly_smiling_face:

2 Likes

My suggestion would be to take a look at what not just Rust but other languages such as Go, Kotlin, Python, etc. present on their front pages. Are there recurrent patterns that can be thought of as "best practices"? Do any one of these pages stand out in either a particularly good or bad way? I think surveying the landscape just like one would do when designing a major language feature could be very illuminating in this regard.

6 Likes

Here are some languages where there's a live online playground no more than two clicks from the language's home page. Swift should have one of these also.

10 Likes

One thing that could be quite useful is a playground, like the ones the Go and Rust provide. This could be the perfect starting point for those wanting to dive in :slight_smile:

4 Likes

A Swift playground is definitely something that we want to add to Swift.org at some point. I know there were some discussions about it already in the SWWG announcement post.

I think it remains to be seen how complicated this would be to achieve but it's definitely not a small task. As there are some things to discuss and consider on the matter, it might be good to start a dedicated discussion thread for this. I encourage anyone who is interested to set one up. :slightly_smiling_face:

@0xTim had the idea to link to https://swiftfiddle.com in the meantime, which I think sounds great.

2 Likes

Sure, I get why it is difficult. Hopefully when the larger restructuring is done, we would be able to show tailored snippets for people looking to build servers, or CLI apps/scripts, GUI apps, ML training programs using autodiff, etc.

But in the mean time, I don't think it's impossible to identify some common packages (say, Vapor, argument parser, async algorithms, maybe even SwiftUI or Tokamak) and have a little carousel of maybe 4-5 very short code snippets. Maybe also one with strongly-typed Regex literals or RegexBuilder - you know, stuff that we'd like to show off a bit. If we could squeeze an Optional in one of them without it becoming too complex, that would be a nice little bonus (maybe a function accepts an optional string or returns an optional value).

Personally, I find it a bit surprising how little code I see on this official website for a programming language.

I think code should feature much more prominently; especially because code legibility is consistently cited as one of the reasons people choose Swift. We don't need to hide Swift syntax.

6 Likes

Agreed! Using a tabbed interface for code snippets is a common "Show, don't tell" pattern and is quite effective. It is even more powerful when the visitor can run the code samples in the playground, but that might be challenging with dependencies.

2 Likes

This, especially, is something I think we should keep in mind while making these improvements. We should show some actual code, even if it's just a simple, static code block.

I think promoting server Swift is the way to attract more users.
If people do Apple platforms, they don't really have other options (beside those awful write once for everything craps).
But if someone is to explore world of programming for servers, there are plenty of established players. And I would love Swift to be one of them. Does at least Apple have some major services built in Swift in production?

4 Likes

One way to promote this that we have been thinking about is a "Use cases" section showing what Swift can be used for and where. Swift on Server would definitely be one of them!

I like the idea of a "showcase" where some selected projects/services that have adopted the use case can be mentioned.

For instance, Amazon Prime Video.

cc: @0xTim @tomerd

1 Like

let us not overcomplicate this. if amazon does not object, we should add their logo to the front page, above the fold, the way MongoDB or Go do with their consumers. just this one simple improvement would go a long way to dispelling “SWIFT is only for APPLE” cloud.

1 Like

I think what is missing on swift.org is something about best practices, going beyond the descriptions of the language in the Swift book and the SPM documentation, e.g. some rules like this one — of course, best practices might be controversial…

1 Like

I installed Swift on Ubuntu a couple of times, and seeing very similar content on Getting Started and Downloads was extremely confusing. I had to compare the instructions point by point to figure out which one is more complete and accurate (and after a few weeks, I can no longer recall which one is).

3 Likes

This is maybe something for the new Swift Documentation Workgroup to think about.

cc: @franklin

1 Like