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.
This opinion is unfortunately common in the Haskell community and one of the biggest things holding back Haskell adoption. I'm a big fan of Haskell (see my recent comment history), but types are not sufficient documentation. Doubly-so with the cryptic symbols / function names that are so prolific.
Python, PHP, etc... are incredible in that every single page of their standard library docs have fully worked examples. When you're trying to get things done, it's great to have a foundation to start from and see how others have done something.
A large part of this (and why you will find it hard to find Haskell developers who admit the state of the documentation is lacking) is that documentation isn't bad -- it's specifically apprentice-level documentation for specific libraries/use-cases that is bad.
In other words, journeyman users who are experienced in "following the types" will find plenty of really high-quality documentation. Total novices who need an introduction to the language will also find high-quality material (though this is more of a recent development).
However, once you're past the novice stage and at the apprentice level where you want to accomplish something specific using some libraries, there's nothing for you there. You have to ask someone at the next journeyman level to sit with you and guide you through following the types.
The thing is that the types are so good that they usually act as ultra-descriptive irrefutable documentation. I've found tons of straight up incorrect documentation in semi-popular Python libraries, but you're never going to find an incorrect type in a Haskell library doc.
As an example, I was doing some password hashing stuff a while back. The most popular Python library had horrible docs where all the arguments were strings and it was ambiguous what exactly went where. The Haskell library had almost no prose docs, but the type signature was something like
Password -> Salt -> Difficulty -> HashedPassword
Literally impossible to mess up.
Personally, I'll take Haskell type-based docs over any other extant documentation that I've come across. Learning to read types effectively and quickly is a bit of a learned skill, but it comes naturally with a bit of use of Hackage or Stackage.
Also, Haskell has services like Hayoo or Hoogle where you can come up with a type signature and it will tell you anything that had that signature. Like let's say I want a function that goes through a list of maybes and returns them all if none of them are Nothing. I just search for
[Maybe a] -> Maybe [a]
I get "sequence", which is the correct answer. Good luck doing something like that with the Python or Java docs.
> why there hasn't been more uptake of Haskell for all of the apparently cool ideas that are there,
People already know how to get the job done one way or another and learning new stuff is hard. It's an unfortunate but pragmatic viewpoint for many people.
Do you think it would be dramatically improved if Haskell had a bigger community of people contributing user-friendly libraries and tutorials? That was something that made Ruby the perfect newbie language for me. And something I feel is downplayed in Haskell given it's more advanced user base who is a little too obsessed with it's power and demonstrating their knowledge as such, rather than help make it accessible to others.
I can't count the amount of times I came across a popular Haskell library with very little documentation rather than it's type/function API and general blurb about what it does. This is very different that most popular JS/Ruby/Python/etc libraries which include quick-start/getting started/usage examples/etc etc.
I am one of the people who are interested in Haskell and find its documentation lacking. I don’t miss comprehensive language books, I miss module documentation. It almost looks as the Haskell community has something against examples in documentation. I stress that the types are not enough. Contrast that with Elm, where I was able to write a working app in a day or so. But Elm is written off quite harshly in the post, so I am again left with the feeling that Haskell may not be the language meant for people like me.
One of the points the author touches is documentation. I just couldn't get why then he gave advantage to Haskell, since the documentation of Haskell libraries famously consists of a few definitions of types. So, you know that there is an abstractly named monadic function, you know it takes a foo and returns monad foo. What more guidance would you ever need?
But when it comes to CL, he has expectations:
>I’ve opened an issue on GitHub of one quite popular library, asking the maintainer to write documentation, but after 6 months it’s still not written (strange, right?).
Yep. I agree reading other peoples Haskell can be a challenge. There is a real culture of making your code as terse as possible, which I think makes it easier to read once you know what you are doing, but makes it harder for beginners.
Luckily Haskells type system means that you can understand a lot about what is going on just by looking at the type definitions. Most code includes these. Although rather frustratingly, however, a lot of documentation doesn't include the type definitions. It is good to see languages such as Idris make it mandatory to include type definitions for all functions.
Yes, Haskell is missing tutorials, how-tos, stuff that make those more complex concepts easier to understand.
As an example, the single kind off complex library I created (called "interruptible") is still lacking a good explanation of what it is good for, because despite having created it to solve a specific problem of mine, I still could not find a good way to explain it.
On the one hand, the parent's comment is certainly hyperbole.
On the other hand, it's also the case that too any Haskell projects are under-documented. Probably worse than the typical language, and certainly worse than the best-in-class.
On the gripping hand... while types make poor documentation, they are always correct documentation, and they are automatically generated documentation. When I write Python or (apparently) Common Lisp, I can expect to get reasonable documentation by interrogating anything someone hands me. In Haskell, insofar as I have learned to get good information from the types, I get some (correct!) documentation for things that I have newly assembled myself!
I taught myself Haskell to an intermediate level a few years ago, and I think you're touching on the truth here.
Haskell is hard to learn, or at least it was for me. There is a whole laundry list of concepts I had never even heard of that I had to understand before I could do anything real with the language. Some were apparently dead simple yet frustratingly abstract (e.g. Monoids). Some were intuitive but still took time to grok (e.g. list manipulation stuff). Some twisted my brain into knots and only yielded to persistent study and practice (e.g. monads with threaded state).
As I was working through all these "basics", I was constantly frustrated trying to write simple programs. I don't recall whether I blamed it on a lack of beginner-friendly documentation or not, but slowly it all started to resolve into a coherent picture and once I could consistently read and understand real-world types I found that the available documentation was almost always enough for me to quickly understand an interface and how to proceed in using it.
I think both sides of this debate are partly right. Haskell's learning curve seems to keep going up as far as you want to climb, and some of the stuff at the intermediate level IMO could really use more examples and documentation, or at least that was my opinion when I was looking at it a year or so ago. One good example might be Template Haskell, which pissed me off to no end every time I tried to use it even in very simple applications. It involves a lot of new syntax and concepts and IIRC had literally no documentation besides what Haddock gives you for free.
On the other hand, I think a lot of people criticize Haskell's documentation without knowing the language well enough to make use of said docs or even understand how they might be useful. IMO it's unrealistic to expect every module and library to provide documentation specifically for beginners who don't understand challenging yet ubiquitous concepts (like state monads, to use your example), and I don't think other languages necessarily do a better job at this, but Haskell is just so darn tricky to get your head around that the "total beginner" phase lasts way longer than it might in e.g. Python.
For beginners who do want to learn about the core concepts of the language, I found that there was plenty of material to help me on my journey: Real World Haskell, LYAH, the IRC channel, and the internet full of blog posts, to name just a few. I don't mean for this comment to cause offense, or to belittle anyone. I'm certainly not an expert Haskell programmer, and there is much that I still don't understand about it. I just wanted to share some insights I've had learning it and using it in some practical applications.
None of what you wrote contradicts that examples could be given in the docs.
But defending the lack of documentation kind of shows why haskell will not see much adoption.
Also, rust for example is much more rich when it comes to examples in docs and rust people could also argue to not provide docs because of type signatures. They just decide to provide documentation and succeed in attracting people.
I have in most years learned some nicher languages: Elm, Rescript, Racket, Common Lisp.
But nothing is even remotely bad as Haskell is.
Even just setting up an IDE to have basics like syntax highlight or go to definition is a giant chore.
On the official Haskell devcontainer offered by GitHub is nearly impossible to add any external dependency, so having a one-click shareable Haskell environment in the cloud (the very basic to onboard people on the language without wasting them days into having their own inconsistent environment) is a must.
Another thing that I feel sucks is the default documentation for Haskell libraries. Doesn't say anything useful at all, bundles few definitions here and there, 0 examples, and more often than not there's 0 documentation.
I was a Haskell developer in my last gig. I entered that job determined to make a success of it, because I was excited about the language and felt I wanted to "prove" that it had value in a "boring" domain like financial services. But I was stymied at every opportunity by Haskell itself.
My biggest complaints are 1) the lack of good libraries, and 2) the apalling state of documentation for the few that exist. Too many Haskell projects read like "I figured out this neat family of types for thinking about X - at last URL parsing is provably safe - now you figure out the rest".
Let's take a practical example: HTTP requests. If I'm a budding JavaScript developer, or Kotlin developer, or Python developer, I can read through copious search results and tutorials on Axios / OkHttp / Requests / delete as appropriate. These tutorials not only walk me through the common use cases but also show me their APIs in the context of the new and alien syntax of the language I'm grappling with. They give me enough template code that I can use an incomplete understanding of whatever language it is I'm learning to figure out the rest without recourse to a textbook.
What does Haskell have? It has Req (and a bunch of other also rans), and the docs for Req are atrocious, spanning a staggering 1 (one) example and then a meandering essay on the deficiency of other Haskell HTTP clients. It's not good enough.
And that's my assessment of Haskell as a whole - not the language individually, which is expressive and powerful and inspired - but the whole ecosystem around Haskell that feels like a set of beta projects and hobby repositories generally developed by interested individuals rather than commercial endeavours.
Or look at the paltry state of IDE support. It's 2020 and the best option we have is VSCode with HIE, which rapidly spirals out of control allocating memory, randomly crashes and on Windows just refuses to even start half the time. Without this tooling a lot of the theoretical benefit of the type system is being lost. This is low hanging fruit but there's been no incentive to pick it.
And so I've made the difficult decision to leave Haskell behind. If you need typed functional programming, your options are OCaml, Scala, F# or even subsets of Rust and TypeScript. Haskell is a great learning experience but totally unproductive right now.
But I've found it semi-refreshing to be confronted with something that is different enough that I have to sit down with it regularly to practice. It isn't just another language, and it really isn't amenable to just fiddling with things until they work.
That said, the gap from newbie to competent is big, an I feel like this is mostly a documentation issue. I've only started very recently and I have awhile to go. You can't expect to grok the implications of monads, laziness, immutability, and pure functional style immediately. But hat doesn't mean they aren't worthwhile, or interesting.
Now if you'll excuse me, I need to harass, er, ask for help on some Haskell I'm stuck on. (BTW: the community is really helpful. There are no charlatans or self-promotional jerks like you'll find elsewhere.)
The Haskell community identifies "no documentation" as a key flaw of their own community? I was going to ask why there hasn't been more uptake of Haskell for all of the apparently cool ideas that are there, but nevermind, I don't think I need to ask now.
Somewhat off topic: My problem with Haskell is that every time I've tried to read the documentation, I've felt like I needed a PhD in type theory to understand all of the terminology. As a practitioner (not a researcher), I just want to know how to do things, but the documentation has always been a roadblock to me. So, after a number of attempts at learning to use Haskell, I've decided its not for me. Not because of the language itself, but because of the traditions around it.
I love haskell but I wish there was less blogging about why everyone else should use it and more building things that will make people want to use it.
The community is extraordinarily friendly to beginners, as long as you only count how they interact with beginners. If you count having resources that allow beginners to figure something out without having to ask then they are extraordinarily unfriendly.
If I find a potentially interesting library on hackage I'm no longer surprised to find it has no documentation at all, certainly no usage documentation or explanation of what it actually does or what it should be used for. Just code and autogenerated API docs. I'm surprised if there is anything that would allow me to actually use it. I'm not often surprised this way.
That and the wild west, "not invented here", multiple incompatible implementations of new ideas used in different important libraries (iteratees at the moment).
Not trying to throw blame around of course, but people probably don't need your "I have a new metaphor for monads" blog post or an argument for why it's worth learning. People need more posts like the 24 Days of Hackage(http://ocharles.org.uk/blog/) series and the Real World Haskell book and they need some brave person to try and convince those amazing library developers to standardize on an imperfect solution a little sooner and for a little longer (only in public of course).
That attitude is not representative of the community. Some people would like more documentation and some are content, but either way it's still Haskell and the types get you very close to full understanding.
Haskell is fantastic. In fact, it is by far my favorite language. Strict types and functional programming come together in a perfect union. Monads are very similar to JavaScript callbacks, actually. After extensive use of the language, I finally decided to give it up for 2 reasons. 1) Stack and package management. Specifically, after building many websites with Haskell's "supposedly" production ready framework, Yesod. After an upgrade, every site I made completely broke and there was almost no documentation on any version changes for this framework. Which leads me into complaint 2) Lack of good documentation. I'm not trying to take sides on the debate of self documenting code, however, when using higher level libraries, it is completely infeasible to rely on reading source code to determine what a function does. Haskell programmers believe that because of such strict typing, the code should speak for itself. Unfortunately, the real side effect of this is you end up coding trying to match up your types instead of focusing on your goal at hand.
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...
reply