On the website, the description of language features are lacking

l1n3n01z commented 3 months ago

Problem

I had run into Gleam a couple of times as a BEAM language on the interwebz and even checked out the webpage once, but I was not really interested in exploring it further until I listened to an interview with Louis on Software Unscripted . The reason was that I didn't really see the value in Gleam. However, after listening to the interview and understanding what makes Gleam a great fit for myself, I'm much more interested.

I'm a mostly backend developer. I write mostly C# but have been moving to F# in production and a colleague is also making me envious with his Elixir project, so I think Gleam might be a great fit for upcoming projects, marrying ML syntax and BEAM and OTP.

Caveats

My only knowledge of Gleam is from the interviews on Software Unscripted and half an hour of googling. So this is very much a "first glance" feedback. Also I don't use any BEAM languages for any projects, only played with them and worked a bit through Elixir in Action.

Suggestion

Update the front page of the website. Currently it's very hype and friendly, but it lacks some concrete points.

Things I think are missing from the front page, either in the form of bullet points or links to further pages that go into slightly more detail

There is a working and AFAICT fairly feature-full lsp. The front page mentions "editor integration" which is not very concrete
Treesitter has a parser for Gleam.
Gleam has it's own OTP library. OTP is a big draw to BEAM and a big learning curve. Maybe link to some good documentation (which also seems to be missing) for the OTP library?
Does Gleam have it's own Phoenix? It seems that, yes, Wisp seems to be a decent web framework (An aside: The Wisp website is far more concrete than the Gleam website and gives a better overview of the value proposition.)
What kind of a typesystem is it? It would be good to mention that the typesystem (I'm guessing here..) is a fully inferred ML style typesystem and draw comparisons with ELM, F sharp or Ocaml. And even show how the type system is different from what people would normally expect from a static typesystem like C# or java.
The package manager could be fleshed out ever so slightly. Maybe just include a link to the package manager documentation? Is the search story in the cli good?
I think having links to interview and talks would be very valuable. And maybe links to some other great BEAM/OTP resources, like Elixir in Action?
What is the NIF and interoperability story for Gleam? A link to a short example using c (or rustler or zigler) would be great. Showing how to call Erlang code would be great. The gleam book shows a call into javascript which is probably not the best example. Something like this should definitely be linked from the front page: https://www.jonashietala.se/blog/2024/01/11/exploring_the_gleam_ffi/
Spell out some value propositions:
- What is the value for the Elixir programmer? The type system, obviously.
- What is the value for the Scala or F# programmer? I would say OTP.
- What is the value for the Java or C# programmer? OTP and syntax.

lpil commented 3 months ago

Hello there! Could you give examples of programming language home pages which do cover all these points? I'm interested in how they manage to fit this detail clearly. Thanks

lpil commented 3 months ago

Closing due to inactivity. Please feel free to reopen with the info, thank you.

l1n3n01z commented 2 months ago

Sorry for the late response!

I'm not sure a landing page can cover all those cases. However, having links in each paragraph would help a lot. Also, I wouldn't necessarily expect that all the points I made would be addressed, but a page with links to talks and blogs would help a lot. Awesome gleam has some resources but it's not linked anywhere from the gleam page AFAICT. https://github.com/gleam-lang/awesome-gleam?tab=readme-ov-file#resources

I think fairly good examples of this being done well in other languages are roc, zig and elm. They lay out a value proposition and then have links to details on what those values mean, concretely.

Zig has the in-depth overview where you can read about memory management, errdefer, bounds checking, comptime and interoperability with C. Roc has very clear values: fast, friendly, functional and then explains what those terms mean in more detailed posts. Elm doesn't talk much about the language itself but highlights it values on the landing page and then links to blogs or the guide that explain what that means in practice.

I believe having links from the paragraphs on the landing page would very helpful, but even just having a single link to the FAQ would be great. There is no link to the FAQ on the landing page!

Reliable and scalable could have a link to how to use OTP with Gleam and possibly a link to something offsite about OTP and how concurrency works on the Beam in general. Elixir School has some nice tutorials about working with GenServer and OTP in general, something similar might be worthwhile having on the site and easily discoverable. Add an OTP section to the tour?

Here's something that could be linked to right away: https://github.com/bcpeinhardt/learn_otp_with_gleam?tab=readme-ov-file

Just adding links from the Ready when you are to a blog or documentation about the build tools, package manager and language server would be great. What features does the LSP support? Could you have little animation that shows the LSP in action? Does the package manager allow different versions side by side in the same project? Is there a lock file? Can you update packages individually from the command line like dotnet nuget add package?

Adding a link from Here to help to an in-depth article about the type system for people not familiar with similar type systems. When are types inferred? Can you still have explicit types for documentation? How can the language not have nulls or exceptions, what do you do instead? And something for the Haskell programmers, explaining that no, Gleam does not have higher kinded types and the reason for that. Possibly another link about use expressions and a tutorial showing how they add value. How does railway oriented programming look in Gleam? How does partial application and/or currying look like?

A link from Multilingual to the blog post I mentioned would be a quick win. https://www.jonashietala.se/blog/2024/01/11/exploring_the_gleam_ffi/

Adding a new paragraph, "Ready for real work" or something along those lines where you highlight how to get started doing a web application with Wisp or how to use cowboy with Gleam might be a good candidate. Or a link to a blog from a company that uses Gleam and what they are happy about and what gotchas they ran into.

l1n3n01z commented 2 months ago

Closing due to inactivity. Please feel free to reopen with the info, thank you.

I couldn't find a way to reopen the issue.

lpil commented 2 months ago

Thanks for the examples. We studied them in great depth when making the Gleam website, and I think we offer the same the same high level information they do. The things you are asking for to me seem as niche and specific to your particular desires, they are not things that anyone else has asked of the home page. It also cannot be a navigation hub for all documentation in the ecosystem, that would make it fail to achieve its intended purpose of being a brief and high level elevator pitch for the language that directs you to the documentation hub or to the language tour.

l1n3n01z commented 2 months ago

First of, I have to admit that I stupidly assumed docs was just that: Documentation of the language and not a list of helpful links.

Either my bad completely or possibly an UX issue. A few lines of text on the page itself "Here is some further info and links" might be helpful for us who are strapped for time and jump to conclusions?

I agree that you offer the same high level information as the languages you mentioned, but not the same discoverability of deeper information. Links inline with the reading material is key. Something piques my interest (editor integration) and then I want to have a link to a better explanation to open in a new tab instead of thinking of scrolling up to see if there is a link to deeper info in the docs link (which I only glanced at before scrolling down to read the overview).

I see that you have been writing an overview documentation recently for the language server as a page. Why isn't that page linked from anywhere? This is precisely one of the pages I was looking for a link for.

Some of my examples were quite niche, agreed, but to me it seems that Gleam is a niche language for people with specific wants and addressing those wants in detail seems important. I listed a lot of examples, as examples do give you an idea of what might be relevant to someone who might consider Gleam to solve their problems at work. Not all of them are relevant to me at all but are relevant to my coworkers or possibly a random redditor.

I made suggestions that could be implemented without going away from the website, but simply by linking to the relevant section on the docs page or to a blog post. So there's not really any need to to be a hub of all the documentation in the eco system.

My guess is that no one has asked this of the home page, because very few people who drop by will take the time to explain why they just stopped for a couple minutes and then went away. The reason I did was because I had seen the website, looked elsewhere, but then came back after hearing interviews with you that actually managed to sell me on the language as something that might be a good fit for work. I also assume that the people who have been happily putting in pull requests to update the documentation pages have not wondered about how well the landing page performs because they are not the target audience for the landing page as they are already sold on the language.

gleam-lang / website