Illustrate features of Pony with Code Samples

[mfelsche]

In this hackernews conversation: https://news.ycombinator.com/item?id=17195580 , lots of people demanded code examples on the website. They couldn't find any, even after clicking around.

I think it makes sense to give shallow first impression with some code example that highlights some of the strengths of pony and to provide some more examples on a separate page, centered around how to do common things in pony, people might be used to from other languages.

[SeanTAllen]

I disagree.

Is anyone going to use Pony because of those examples? Probably not.
Will people decide not to use Pony because of those examples? Quite possibly.

People want many things. Whether those things are valuable or useful or not is a different story. If we have a valid reason for providing examples of how you do X in Pony then ok, but "people want to see code examples when briefly doing a pass by on HN" is not a good reason to me. There should be a reason for those example.

[SeanTAllen]

@mfelsche and I chatted a bit. I'm quite good with approaching this as "impression should someone have after a quick visit to the homepage" and working from there to figure out what in terms of text, code, images, videos etc should be there.

The key for me is having a goal besides "put some code on there". We should have a defined goal and figure out how to meet that goal via whatever means (including code).

[mfelsche]

The main goal i would like to pursue is to have the visitor of the website, especially newcomers to pony, be able to get a good first impression of the language and if they want lead them to other sites for further information (like the tutorial or the stdlib docs).
Seeing the actual language as code example is not necessarily part of such a first expression, but it is something people are interested in, in general. And this desire is understandable as we are exhibiting a programming language here. The main interface to the language is writing it, so people have a legitimate interest in seeing what they might have to write to make certain things work or leverage certain properties of the Pony runtime...

So, to clarify, i don't want code examples for the sake of having them, but for the following reasons:

• Syntax is an integral part of the language, although not the most interesting part of Pony, i have to admit. (Furthermore the pony syntax is nothing to be ashamed of. I do like it a lot.) Hence, a visitor who would like to know more about the language should also be able to find out, what it looks like.
• Code examples are a great way of illustrating features of a programming language. The website is full of descriptions of the features of Pony, these would be more insightful if illustrated with code examples. They also serve the purpose of teaching people can leverage or work with certain properties of Pony. (Say e.g. the property that messages sent to actors are only pointers being moved through mesage queues, finally passed into some actor behaviour. Seeing how simple this is by the help of a code sample might make people appreciate the language as much as i do.)

[plietar]

A central aspect that the front page should show off is actors. Most readers coming from other languages will not have used them before, and even people coming from eg Erlang have used a very different style. This is IMO what really differentiates Pony from other languages (maybe I'm biased, coming from Rust/C++).

But just having text explaining what actors are is not going to grab attention.

If we had a simple example (like two actors, just doing ping pong) that demonstrates how easy and intuitive actors are in Pony I think it would help a lot.

[SeanTAllen]

I agree with @plietar re: actors. I think something that shows actors is certainly part of it. Hello world while there is more than 1 actor is very non-obvious and wouldn't be a good idea in my mind. Ping/Pong might be good.

Ref caps are an integral part of Pony as well but, do we show them that early on? I think not. Or rather, we don't highlight them.

I think something like Ping/Pong with an explanation of what is going on could be good.

Showing code for the sake of syntax is in my mind, unimportant. If you are coming for to see the syntax, you aren't getting over the hump of reference capabilities. That's the wrong audience for us.

So, if you want things to highlight I think it should be:

safe concurrency via actors. that's the hard problem that pony is solving. its what needs to be emphasized. I'm not against code samples but they should be specifically to demonstrate what makes Pony different.

Its a serious investment in time to learn Pony. People need to be presented with a case for why they should do that.

[SeanTAllen]

One additional note, I'm worried that Ping/Pong wouldnt end up demonstrating enough. We might need something a bit more interesting. Find a good example that is accesible in terms of problem domain yet also demonstrates what we want could be hard.

It might require more than 1 example but a single example would be best in my mind. Perhaps something from examples in the repo.

[thomastay]

Reviving this old issue as I've been thinking about this too. I also disagree that code samples are that important, especially since syntax isn't Pony's strength.

I think it's most insightful to take a leaf from other languages' websites. Below, I will analyze some of the top rising languages in 2020:

Rust

https://www.rust-lang.org/

• Has a splash logo, the language name in HUGE FONT, a tagline "A language empowering everyone
  to build reliable and efficient software.", and a "Get Started" button. All things which are immediate in drawing attention. Importantly, users self-classify : those who want to use Rust will get started, users who aren't conviced will read on.
• On that note, the Get Started page takes them immediately to the install page. There is no choice in this matter, which is good in guiding users. Remember: this target audience is users who already want to use the language.
• For users who aren't convinced, scrolling down the homepage brings you to "Why Rust?", with three taglines:

1. Performance - Rust is blazingly fast and memory-efficient: with no runtime or garbage collector, it can power performance-critical services, run on embedded devices, and easily integrate with other languages.
2. Reliability - Rust’s rich type system and ownership model guarantee memory-safety and thread-safety — enabling you to eliminate many classes of bugs at compile-time.
3. Productivity - Rust has great documentation, a friendly compiler with useful error messages, and top-notch tooling — an integrated package manager and build tool, smart multi-editor support with auto-completion and type inspections, an auto-formatter, and more.

• The Homepage then follows with 4 classes of apps that can be built in Rust, along with 4 links for the unconvinced user to self-classify themselves, and read the guide that is tailored for that particular group. When you click on 1 of the 4 links, now only do you see the code samples.
• You see a Testimonials section, where there are big splash quotes from prominent users who've used Rust.
• Then, a "Get Involved" section. Personally, I think that section is unhelpful for new users and is mainly for existing users who want to deepen their knowledge.
• Laslty, a "Thanks" section, linking to their backer page.

Comments

Notice that there are no code samples. There is just one line about the borrow checker. Nothing about syntax. Nothing about error handling. It's all about what Rust provides: a No GC language that happens to have a great type system. And more importantly, it's about the problem domains that Rust solves. They really neatly categorised them, which is nice as a developer.

Typescript

https://www.typescriptlang.org/

• The page opens with a huge splash image of Seattle. This is odd for many reasons, but it is beautiful.
• The word "Typescript" is in huge font, along with the tagline: JavaScript that scales.
• Then, a brief explanation: TypeScript is a typed superset of JavaScript that compiles to plain JavaScript. Any browser. Any host. Any OS. Open source.
• Following are two links, "Download" and "Documentation". Once again, this is to **self classify ** users. Those who are convinced click on "Download", those who want to learn click "Documentation", those who are unconvinced read on.
• Scrolling down, we have a Carousel of Twitter testimonials on how Typescript helped them. This helps to inspire unconvinced users.
• Then, we have the "What is Typescript good for" part. They focus on three areas:

1. Starts and ends with JavaScript
2. Strong tools for large apps
3. State of the art JavaScript

• Obviously, you can tell from just the headlines that they are targeting enterprise Javascript developers. Indeed, that is exactly their target audience.
• For those who are now convinced, they have a "Learn it fast" button, which links to the same Documentation page above
• For those who are now convinced and wanna get the shiny toy, they provide immediately CLI instructions for downloading, as well as Editor support.
• Below, we see a See ts in action section, with a video of Anders presenting on Typescript.
• Then, they highlight Typescript is Open source, because every language in 2020 has to be. (and because Microsoft knows of its reputation)
• Then, another carousell showing off more testimonials from Enterprises (the one above was from users)
• Lastly, a "Get involved" section and another "Learn" section.

Comments

The Typescript page is less convincing for me than the Rust page, but I think Typescript is targeting a different group. Namely, engineering managers / architects who already know JS intimately, and are looking to upgrade their front end apps. To those people, they probably know why types are important, Typescript just has to convince them that it is stable enough to be adopted in their organization.

Again, there are no code samples. It's all about how stable Typescript is and how clean it is. I really doubt many will watch the video, but having a video there shows commitment! It shows that people like this language enough, that they made a whole video on this. (For those unaware, MS Build is a huge Microsoft conference, and to be featured there is a big deal; F# wasn't even featured in this year's MS Build and it's an older language than TS)

Go

I don't want to make it sound like I'm bashing code samples, so it's just nice that the next language I picked, Go, has a lot of code samples on their website:
https://golang.org/

• The page opens with a big tagline, Go is an open source programming language that makes it easy to build simple, reliable, and efficient software.
• The Go Gopher is prominently featured, alongisde a large button that says "Download Go". Obviously, this is for users who are already convinced.
• On the right, we see a lot of code samples! We see Hello world, Game of Life, Peano Integers, Fibonacci, Concurrent Pi, Concurrent prime sieve, Trees. More importantly, these examples each show off a specific aspect of the Go language. (see the page for more details, there's too much to summarize here)
• If you liked the code samples, there is a link that will take you to the Go Tour. But this button is tiny and hidden, and so might be lost on a first look.
• we see featured articles on the bottom left, and featured videos on the bottom right.
• That's it!

Comments

The Go website is minimalist, reflecting the developers' philosophy. Indeed, the Go language, Go tutorial all follow this design scheme of minimalism. For instance, the Go playground doesn't even have syntax highlighting.

More interestingly is the abundance of code samples. My guess is that Go can focus on this, since its syntax is so similar to C like languages that anyone with a programming background can understand most of it.

Very little is said about Go's strengths, namely its easy concurrency handling, its huge standard library, and its minimalist syntax.

Overall, a nice contrast from the marketing-heavy websites above.

snark: It's kinda funny that Rust and Go both use basically the same tagline...

Dart

https://dart.dev/

• Wow! The webpage opens with a fluid animation of a swivelling phone, and the splash intro appears Paint your UI to life, with Dart VM's hot reload
• Scrolling down, we see the tagline: Dart is a client-optimized language for fast apps on any platform
• We also get to watch a video, but it is a link, not an embedded player.
• A big "Made by Google" sign right there.
• Then, a list of features, much like Rust/TS, along with a quick description

1. Optimized for UI
2. Productive development
3. Fast on all platforms

• Then, the website explains each of the features in depth. It has UI cards for all three features, each card having 2-3 bullet points explaining the feature. If you mouseover each bullet point, different code samples appear next to it.
• A note: the languages Dart compares itself to are TS, Kotlin, and Swift, reflecting Dart's focus on mobile dev.
• Then, we see a "Try Dart in your browser"
• Afterwards, there is a very tiny URL link (not even a button!), encouraging you to download Dart.

Comments

The animation is super smooth, they really hired good designers for this. IMHO, I think this website is designed to convince people to use Dart. The target audience is mobile app developers who have never heard of Dart, who probably won't use Dart right now, but might in the future. That's why there is very little focus on getting Dart installed on their computers.

The focus is on convincing you, the reader, that Dart is a good language that you might consider for your next hobby project, and hopefully later on, your next company project.

This reflects Dart's position - It's definitely not as big as Kotlin / Swift / Typescript for mobile app dev (TS thanks to React Native). So, it has to compete by focusing on impressing new devs, even those who probably won't download your language.

will add more

[damon-kwok]

@mfelsche Is this what you want?

@SeanTAllen We can open a discussion topic in zulip and collect the most representative code of pony. It must have the characteristics of pony and the most spiritual representative. I think it's good if it is up to expectations. When I first logged in to ponylang.io, I was actually very eager to see this.

[SeanTAllen]

@damon-kwok I will argue against all those as a waste of space.