Almost every time (though it's quite rarely) that I end up on a Haskell documentaiton page, I facepalm and move on. Yes, there's a dump of inpenetrable types. But... how do I actually use those types? :)
1) a simple instance of use of the language feature
2) a few typical instances of use
and
3) did NOT use towers-of-hanoi, prime-sieve, mathematical smartness, pointless tricks unrelated to the core functionality, dubious features under dispute..
The best UNIX man pages for systems commands do exactly this. They show all the commandline options in the sort-of BNF, they list the meaning/intent of the options (hopefully alphabetically) and under EXAMPLES they show you the 3 cruicial commands you really came looking for, exactly as the worked when the manual page was written.
I know I used man -s 1 or -s 8 to exemplify how to do man -s 2 and man -s 3 pages, but the point is they obey some simple (BNF) norms, some simple (nroff -man) format and EXAMPLES exemplify real-world use. Not "I am smart, watch me put a fruitloop in my nose" but real world, applicable instances.
99 out of 100 times someone will land on this page and already know what regexes are. So basically 1/3 of the page is useless. After a while you find you need to use the `match` method. Great! Now I see I get a match object. How do I deal with those? There is not a clickable link here. In the example it's an opaque object. So I scroll further maybe ctrl+F to find match object. Here I find what I'm looking for. So this take me pages of scrolling and then manually searching for the object a method returns. That SUCKS. Everytime I use the re library and need to refresh my knowledge I'm in pain.
Compare this to Haskell: https://hackage.haskell.org/package/regex-compat-0.95.2.1/do...
Great. I instantly see how to construct a regex. The next thing I see is the `matchRegex` function. The bread and butter of using regexes. And what does it return? "Maybe [String]". Literally couldn't be easier then that.
Of course this doesn't hold for every Haskell library and Python library. But this is my general experience.
That said, Haskell documentation tends to be really lacking on some of the basics that other ecosystems get right, like where to start, shielding beginners from functions for more niche usecases, examples of how to build or deconstruct values, or end-to-end case studies. Some of the nicest things to _use_ have an API that primarily comes from typeclasses in base, and don't provide any documentation beyond a list of typeclasses. My impression has been that most Haskellers seem to be on the same page that those things need work, though - I'm optimistic about the situation improving, but it's still hard to recommend to anyone expecting the experience of working with popular libraries from more mainstream ecosystems.
[1] https://bartoszmilewski.com/2014/09/22/parametricity-money-f...
I don't think this is an accurate representation of how the Haskell community itself views the state of Haskell documentation. A large section of the community views the state of documentation as very not best-of-class and strongly advocates for improving it (and views type signatures as a poor replacement for at least examples). See e.g. https://www.reddit.com/r/haskell/comments/2ory86/there_is_a_...
Likewise "Otherwise, toss a coin!" as a response to Cabal or Stack makes me sad. Tooling can often depend on exclusively either one or the other (see e.g. https://plugins.jetbrains.com/plugin/8258-intellij-haskell) and the fact that from a capability point of view, they're converging on the same thing makes it an unnecessary point of friction for new users, although I understand the reasons for why they both came to be.
EDIT: I should detach myself from the usual curmudgeonly HN comment to say that the organization of the article is very well done. I would like to see how non-Haskellers approach it because I think stuff like "What language idioms are available?" is a good way to approach a new language.
EDIT 2: The original Reddit link was far older than I thought it would be. Here's a more extreme (more than I personally agree with) take on the situation, but is a lot more recent: https://old.reddit.com/r/haskell/comments/or93z3/what_is_you...