Correct Arity

Minimal examples vs motivational examples

I have been reading a lot of READMEs to compile a list of Gleam packages I like, and I personally would like if libraries gave more examples motivating their use. That is, not only a minimal example of the most basic usage, but an example application doing something interesting, maybe slightly opinionated or bringing in other dependencies, to demonstrate a cool use for the library. Now, maybe if someone looked for your library then they already know what it's for and don't need a lengthy introduction to the subject, but idk maybe there are potential readers who could benefit from such an introduction.

I will pick on collie because it is actually great, to be clear not saying collie is bad here (it's great!), just giving my personal pet peeve/wanting handholding! It says "A WebSocket client for Gleam." and my question is ok, I know websockets are some kind of persistent two way connection, but what would I use this for, why would it be nice in Gleam, etc? The first thing it tells me is

Autobahn

Collie passes all Autobahn WebSocket test suite cases, ensuring full compliance with the WebSocket protocol specification. You can view detailed test results and compare them with other Gleam WebSocket implementations like Stratus at:

https://vshakitskiy.github.io/collie

I'm sure the Autobahn WebSocket test suite is great stuff for websocket enjoyers and wiskiy put a lot of work into performance, passing all the tests, etc. And these benchmarks are great and make the library more credible, and it's great that there's a mention of existing alternatives. But, what I really want to know is what can I do with websockets that I couldn't before? Is it a low level library for other libraries to build some kind of server framework on? Is it for me to make a Lustre app with? A videogame? A discord clone?

The basic usage is a good start, it is good to see a basic example of sending "ping" to "https://echo.websocket.org". I'm glad READMEs tend to have some sort of quick-start example. I would like to see more of what projects are for, with real examples.

To some extent I can google it myself and read other docs, it's not your job to teach me everything about websockets or suggest project ideas for me. At the same time as an unfamiliar user, introducing "what are websockets for, what can you do with websockets in gleam" helps me more than 100% spec completeness or 7% faster performance (although those are seriously cool too).

That said, don't let me be overly entitled: you make a correct and fast websocket, and I complain because you don't hold my hand whole time! Especially because if you're publishing a library you've likely already done a lot of the code to meet your own needs, so putting it online might not cost you much, whereas writing a bunch of examples might be more of a pain that doesn't benefit you. Well, fair enough, a wise man once said I can't demand anything of you as I don't pay your bills.