Haskell newbie feeling overwhelmed by Haskell's modules and docs

Learn
#1

Since I’ve always wanted to learn Haskell I’ve spent the 2 past weeks discovering the Haskell cosmos.
Last weeks I started a small Project to apply some of the concepts I’ve learned so far and apply new ones such as Concurrency and Parallelism in the future - GitHub - jimixxperez/HSDirBuster: DirBuster written Haskell. (a port of DirBuster: DirBuster is a multi threaded java application designed to brute force directories and files names on web/application servers.).
Somehow I struggle the most with finding and understanding suitable libs/modules. I spent so much time looking at type signatures trying to reverse engineer the source code in order to use stuff. It feels frustrating and unproductive. Is there a better way or am I missing something?
Cheers Jeremy

1 Like
#2

Could you give some examples of libraries where you experienced this? Perhaps the libraries’ authors, or other volunteers, could help by improving the documentation.

#3

One such example I recently stumbled on is the Alternative type class: “A monoid on applicative functors.”
IMO this begs more questions that it answers. Which monoid assuming there are multiples and why? Or is it uniquely determined? How does Applicative come into play?
The documentation of some prominent instances like [] or Maybe does not have more information neither.

#4

For instance I wanted to work with JSON (Un)marshalling.
Found out aeson seemed to be the most popular go to module.
Googling lead to the corresponding haskage site including the github readme.
The github readme pretty much only provides information about the issue tracker, how to clone the repo, and the changelog, similar situation with http-conduit or async.
In contrast I had a positive experience with optparse-applicative, GitHub - pcapriotti/optparse-applicative: Applicative option parser.

2 Likes
#5

Interesting. The usage information for Aeson is indeed on the Hackage site: Data.Aeson

In fact its top-level Hackage page explicitly says

To get started, see the documentation for the Data.Aeson module below.

So perhaps the Aeson README (and the README of Haskell packages in general) should leave breadcrumbs pointing new users to their Hackage pages? (Aeson’s README does have a link to its Hackage page but new users won’t have any idea that they should follow it to find documentation.)

#6

I think it makes sense to address the readme on github to (potential) developers of the package. User documentation should be on Hackage. Although it might be nice to add a a more noticeable link to redirect users that stumble upon the github page by accident.

2 Likes
#7

Thank you a lot for the hint. My bad. Somehow completely missed the top level Hackage page hint for Aeson.
I m was not aware of Hackage’s potential use as documentation. Thought it was a simple Frontend showing meta information about the associated packages.
http-conduit: HTTP client package with conduit interface and HTTPS support. → "Hackage documentation generation is not reliable. For up to date documentation, please see: http://www.stackage.org/package/http-conduit."
For instance refers to stackage. And on the stackage page there is a reference to a tutorial.md file on github :smile:

1 Like
#8

No need to apologise. Quite the opposite in fact! Your experience report helps us understand how new users learn about the ecosystem and how we can help them.

With hindsight I can see that there is an ambiguity about the target audience of the README.md. The complaint about Hackage documentation generation is also out of date (I think) but requires subtle diplomatic wrangling to get something to be done about it.

3 Likes
#9

Paging @Kleidukos to inform them of this thread, since they are head of Haskell Foundation Documentation Task Force and may find it enlightening.

1 Like
#10

I had good experience with docs providing different level of abstraction.

  1. On one hand a “quickstart” section to get a wide spektrum of standard “simple” things quickly done.
    Also useful for Users who already have experience in the topic
  2. Potentially a more “advanced” section showing more specialized features
  3. A section explaining the lib’s design, insights and recurrent pattern.
  4. the API
    and everything accompanied by examples
    for instance the python lib requests which has in my opinion a great doc
    Quickstart — Requests 2.27.1 documentation
    in comparison to what I found on haskell’s side to make requests.
    req → Network.HTTP.Req
    or http conduit
#11

And thanks a lot for the quick reply. The friendliness of the Haskell community precedes its reputation :).

2 Likes
#12

The book “Haskell in Depth” by Vitaly Bragilevsky is a convenient introduction to many important Haskell libraries. If you find this book too difficult, try “Get Programming with Haskell” by Will Kurt first. Both books have helped me immensely.

3 Likes