Comment by dwohnitmok | Hacker News Reader

Comment by dwohnitmok | Hacker News Reader

> Haskell is in the best-of-class category when it comes to documentation. Haskell's type system quickly earns your trust, and once it does, you almost never need to read someone else's code in order to understand it; you can just read the type signatures shown in the docs and get on with your life.

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...

> 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

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? :)

I think this is a very insightful comment. If the documents showed:

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.

If I compare Python docs and Haskell docs even the official python docs are completely terrible. For example let's take the regex library and want to look up how to get match groups: https://docs.python.org/3/library/re.html

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.

I think, coming from other languages, it takes a while to really absorb how much you can rely on types to tell you what a function is doing - to the degree that for some functions you can infer the implementation from them[1].

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...

Cabal and stack are also very hard to understand when starting out.

Rust's `cargo` kicks the crap out of either of them.

Reply on news.ycombinator.com