Improving the content on Swift.org

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:

5 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

Thank you, this is great feedback! I will make sure this gets improved—for all platforms.

Writing High-Performance Swift Code should also be linked to at swift.org.

4 Likes