These definitely look friendlier than average to me :)
Which leads me to think: Maybe the hackage search engine is a bit to blame here ? For instance, lets say that I want to decode some json string (which is, you'll agree, quite a common and basic need, and was for me one of the firsts).
So I'm this newcomer to Haskell, willing to learn, and to parse a JSON file. Naively, I would type "json" in hackage, which would lead me to the json package ... how to use that ? no clue (remember, I'm a begginer)... end of story: I'll do that with a JSON.parse() in javascript.
Now, lets say that I'm an observer, and that I notice that there is a package several lines below which has more downloads, aeson ... welll... that's better, because if I'm curious, i'll click on Encode and find what I'm looking for, written in words, but it's quite a convoluted explanation for such a simple need. "Where's that damn parse method, and why isnt it mentioned on the main page ?", I would think.
As for libraries that I was frustrated not to see working, I dont remember most of them (because I usually just leave), but here are the two which I fought the most with recently:
The one the log in my article refers to : persistent-postgresql, which I didnt know how to install given that it missed pq native lib (which I am supposed to know that is installable via apt-get install libpq-dev, I guess ?), and has no obvious documentation (but agreed, there is one lurking somewhere, which doesnt mention this native library thing... nor does the issues, though, so I guess that's a problem on my computer, somehow).
gitlib, which has quite a decent readme, but is not in stackage LTS. Meaning that I took quite a bit of time and frustration to understand how stack resolves packages, to finally notice that it doesnt compile.
Thanks a bunch for taking the time to go into detail here. I really hope we can use this to improve things :)
It sounds like there's opportunity to better surface usage and activity in Hackage search results. When searching for packages my habit has become to: input my query, sort by downloads, then try sorting by last-upload date. Hackage does have a "Rating" metric for each package (you can vote for packages you like), I like the idea but I'm not sure how obvious it is or how well used. Npm has three metrics they try to surface: popularity, quality, and maintenance. It also looks like they aggregate these somehow into an 'optimal' metric. I've not been able to find information on how that aggregation is done, but there's a little info about the others in their help docs. Rubygems makes the total number of downloads very prominent in their search results. It's nearly at the same level as the name of the Gem. They also have "updated last week" and "updated last month" filters.
Getting from the package contents page to the best starting point in the package documentation could really be improved. This is my habit: if the package description contains a link to a module it suggests is a good starting point: I'll click on it, if not: I scroll down to the module list and try to find the most "top-level" looking module. In that case ideally there's a module that has a name which resembles the name of the package. In the case of Aeson the best starting point is Data.Aeson, but it perhaps doesn't do the best job of directing you to the decode function early enough. Rubygems appears to have a "documentation" link as part of their Gem meta data which, in the couple of examples I've just tested does a good job of taking you straight to that "best starting point" for the Gem's docs. Npm appears to rely on that information being provided in the package's README.
In the case of system-level dependencies something like a "dependencies" or "system requirements" section in the README may have helped at least a little. E.G. in the documentation for the Pg gem.
As for packages not being in LTS: I'm sorry but I can't really speak to that, I use a Cabal + Nix workflow that I can't really say is better or worse but works well for me. It helps that I've really bought into Nix so I'm not sure if I should recommend it for everyone. Developing, supporting and improving tooling is, I believe, on the roadmap for the Haskell foundation.
All great stuff to think about. Hopefully we're able to take some steps to smooth out some points of friction. Thanks again for describing your experience :)
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
These definitely look friendlier than average to me :)
Which leads me to think: Maybe the hackage search engine is a bit to blame here ? For instance, lets say that I want to decode some json string (which is, you'll agree, quite a common and basic need, and was for me one of the firsts).
So I'm this newcomer to Haskell, willing to learn, and to parse a JSON file. Naively, I would type "json" in hackage, which would lead me to the json package ... how to use that ? no clue (remember, I'm a begginer)... end of story: I'll do that with a
JSON.parse()in javascript.Now, lets say that I'm an observer, and that I notice that there is a package several lines below which has more downloads, aeson ... welll... that's better, because if I'm curious, i'll click on Encode and find what I'm looking for, written in words, but it's quite a convoluted explanation for such a simple need. "Where's that damn parse method, and why isnt it mentioned on the main page ?", I would think.
As for libraries that I was frustrated not to see working, I dont remember most of them (because I usually just leave), but here are the two which I fought the most with recently:
pqnative lib (which I am supposed to know that is installable viaapt-get install libpq-dev, I guess ?), and has no obvious documentation (but agreed, there is one lurking somewhere, which doesnt mention this native library thing... nor does the issues, though, so I guess that's a problem on my computer, somehow).Thanks a bunch for taking the time to go into detail here. I really hope we can use this to improve things :)
In the case of system-level dependencies something like a "dependencies" or "system requirements" section in the README may have helped at least a little. E.G. in the documentation for the Pg gem.
As for packages not being in LTS: I'm sorry but I can't really speak to that, I use a Cabal + Nix workflow that I can't really say is better or worse but works well for me. It helps that I've really bought into Nix so I'm not sure if I should recommend it for everyone. Developing, supporting and improving tooling is, I believe, on the roadmap for the Haskell foundation.
All great stuff to think about. Hopefully we're able to take some steps to smooth out some points of friction. Thanks again for describing your experience :)