Add links to gleam packages managed by the gleam-lang org in the documentation page (i.e. gleam-erlang)
PastMoments opened this issue · comments
https://gleam.run/documentation/ has a link to gleam_stdlib, it should also link to gleam_erlang and gleam_javascript, and any others that are managed by the gleam-lang organization proper (or at least those that are relevant).
Users (including myself), often initially struggle to create programs that interact with I/O, as there's no reference to gleam_erlang in the documentation page (or anywhere else I could find).
Trying to read from a file, I'd run into gleam_file and struggled, then had to google to find this forum link, which isn't the most ideal way of figuring this out.
https://discord.com/channels/768594524158427167/1134627144098664458 (an example of someone running into this issue from today)
Hello! Good shout, we should make packages easier to find.
Are you familiar with https://packages.gleam.run/ ?
Hello! Good shout, we should make packages easier to find.
Are you familiar with https://packages.gleam.run/ ?
Yes! It's wonderful, there are a lot of very exciting projects. Although for this particular issue searching "gleam_" doesn't filter very well. (Seems to be similar for all the packaging websites I see)
OK! What are you after when searching for gleam_?
Specifically for the packages page, I'd expect matches to the name to rank higher than usual. As those are probably more relevant.
i.e. packages that start with gleam_ would rank higher.
Now that I think about it I'm just describing a "most relevant" ranking for searches.
My particular issue and the reason I brought it up is that I think "essential" packages should be (significantly) more prominent, which is why I suggested having it on the documentation page where stdlib is linked. Although any other solution would be good.
By essential I mainly mean gleam/erlang and maybe gleam/javascript. Since I'd consider I/O essential.
I don't think there's anything particularly essential about those packages, and I think in future most folks won't be directly adding them to their project. Instead these packages for writing code that interacts with target native code will be implementation details of the libraries and frameworks that the typical programmer will use directly. Much like how in Python or Ruby most projects will be indirectly using modules for working with C code, but very few projects will be directly concerned with them.
I didn't mean to bikeshed this so hard and I'm not particularly hung up on this. I enjoy using gleam very much, I just think this particular developer experience can be improved. (This was a pretty big frustration for an otherwise amazing experience) I'm also mainly motivated by gleam/erlang/file (and maybe gleam/erlang/os), so addressing those would also satisfy me.
Not everything in those packages are essential, but there are things in those packages that are essential. In particular gleam/erlang/file. In python reading from a file is a builtin, in Ruby it's part of the core library. It's part of the standard library in most languages. I think in the future many projects will need to read/write files, and so will need to use this package.
I know Gleam wants a minimal stdlib, especially due to different compilation targets. But because of this, these supplementary libraries that fill the role of stdlib in other languages should then be more prominent (and in my opinion, linked somewhere on the website/documentation). The thought "I need to write a file, which interacts with the erlang VM, which means I need to look for gleam_erlang" isn't particularly intuitive.
My main point is that:
- gleam/erlang/file and gleam/erlang/os should be easier to find.
- There's no easy way of finding gleam_erlang, (and gleam_javascript). without chancing on it or digging/searching. It should be easier to find. (OR making gleam_erlang less necessary for most programs, but making another gleam_file that just wraps around gleam/erlang/file seems strange to me)
I suggested adding it to the documentation page because that's what came to mind first. But some other possibilities are linking to them in the stdlib readme. Or maybe a page of code snippets like "here's how to read a file, how to do I/O, how to do this and that" (this might be a cool idea regardless). Or maybe the part of the FAQ that says "Gleam compiles to Erlang or JavaScript." can also say "If you need to interact with these targets here are the packages for it.
The title doesn't really reflect my thoughts on this issue anymore either. (I basically did the XY problem)
In particular gleam/erlang/file.
This module is going to be deprecated in the next release, in favour of the much better simplifile.
If we disproportionately elevated packages that I maintain you'd likely end up using lower quality packages over higher quality packages just because I maintain them. I maintain many things, it is likely that any community project with a more focused maintainer will be as good or better.
Or maybe a page of code snippets like "here's how to read a file, how to do I/O, how to do this and that"
Definitely! I agree, we need a much greater wealth of documentation. A cookbook specifically like this is planned.
I think your evaluation is spot on. The language is in a good place, but so much of how to use it is unclear. This is something I really want to focus on in the near future, so people can have a much better experience coming to Gleam.