16 ms·

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 a

by moxious 10y ago

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.

chowells 10y ago
Note that it's a contentious issue. Lots of people think there's plenty of documentation. I'm one of them. The people who think documentation is lacking seem to be people who need worked examples of things to understand them. I'm of the opinion that worked examples are often worse than no documentation.
- caconym_ 10y ago
  I agree. The nature of Haskell and its type system means that the basic haddock docs are already pretty darn useful even without hand-written content (examples, etc.) being included.
- barrkel 10y ago
  There's research that shows people learn abstractions better when they also have examples. See e.g. [1] for references. However, I find your tone particularly unpleasant. The sneer in "seem to be people who need worked examples of things to understand them" is repulsive. If this is a representative example of your community, it's one no-one should be proud to be a member of. [1] http://www.maa.org/external_archive/columns/launchings/launchings_12_08.html http://www.maa.org/external_archive/columns/launchings/launc...
  - mitchty 10y ago
    > However, I find your tone particularly unpleasant. The sneer in "seem to be people who need worked examples of things to understand them" is repulsive. If this is a representative example of your community, it's one no-one should be proud to be a member of. Its always good to apply the principle of good faith. You have no idea who you're talking to, are likely going in biased away from someones arguments, and this will be the first time you've ever conversed. On top of that you're hobbled by text. You also don't know if the writer is a native english speaker or not and might consider the phrase "seem to be people who need worked examples of things to understand them" entirely neutral in tone. Communication is a 2 way street, the tone you perceive may not have been intended. And painting an entire group by one sentence, in one post, that you perhaps disagree with, is a bit of an overreaction in almost any circumstance. The tone you perceive is not one I've personally experienced, quite the opossite. As a beginner in Haskell that is still learning, and learns best by examples, the gp's opinion on documentation drives me nuts. But by and large, most examples aren't all that necessary in haskell with the type system. But when you're learning, I have to say, I hate "the types will document everything" mindset. They tend not to when you're a stranger in a strange land. I wouldn't say documentation itself is a problem in haskell, there is tons. I would say the problem is in quality documentation that at least recognizes audiences of disparate skill level would be at issue. Examples help, but if the examples use something like the state monad that you're not familiar with, it probably won't do you a lick of good to understand how to use it.
    - caconym_ 10y ago
      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.
  - efnx 10y ago
    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.
    - moomin 10y ago
      This is only true after you've fully grokked the implications of the types. And, IME, that takes a long time. To give you an example, I spent ages trying to figure out how to create an X. X was a Monad of A. Solution's obvious now...
      - greenrd 10y ago
        Yes, it's a mistake to believe that the type class instances of a type are always going to be advanced details that can be skipped until later. They might be, or they might not.
      - efnx 10y ago
        Examples would help in that case, but there would still be much confusion simply from not understanding Monads (enough to write a computation in that one).
  - monkeywork 10y ago
    If that single line is "repulsive" to you maybe you need to re-evaluate your world view a bit.... stop looking for something to be offended about if someone has a differing view
- omginternets 10y ago
  >I'm of the opinion that worked examples are often worse than no documentation. Counterpoint: this is what keeps me away from Haskell. I really want to learn, and I really do appreciate the formal approach, but being able to do a few simple things quickly (driven mostly by intuition) helps fight frustration. Haskell really does look great, but it's a bit... prickly.
- silluk 10y ago
  I've been coming back to Haskell sporadically over the past couple of months. Every time I do I find the documentation for things like Prelude to be excellent since that's stuff that I already understand but when trying to dive head-first into a new library I end up with 50 tabs open at various points in the doc to try to keep track of all the different parts. For libraries like megaparsec that have not only great documentation but tutorials and examples available it's often much easier to go in and read the "raw" documentation. Haskell isn't like C++ or other imperative languages in that you don't have "these are the method you can use on this class. Good chance you can figure it out from there". That's why I think that Haskell benefits from good example more than "conventional" languages. Disclaimer: I'm very much a Haskell noobie
  - marcosdumay 10y ago
    > Haskell isn't like C++ or other imperative languages in that you don't have "these are the method you can use on this class. Good chance you can figure it out from there". No, but for this case, type holes are much more powerful. You always have an I have X, I want Y, what functions are there that are X -> Y? Hoogle is more powerful than anything I've seen on any other language. (If I could only make it use all the local packages, instead of the pre-built index. I'm sure there's a way.) Haskell has also more need for documentation than most other languages, so hoogle is still not enough. That's the problem, not lack of docs.
- sgk284 10y ago
  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.
- jblow 10y ago
  I am a programmer with a lot of experience who has written a lot of things from scratch (not in Haskell). I think most documentation sucks and I dislike trying to read it, because it's very hard to get a picture of what's going on, and what these procedures / data structures / etc are really for. I am much happier when I can just look at a straightforward and clear example, and then just use the documentation to look up specifics of how things work after I already get the basic idea. It's not because I "need worked examples of things to understand them", it's because that is the way I like to work, because I have had many instances of my life of trying to make sense out of documentation that seems to have been written from a mindset of "formal writing involves not actually telling the reader what things are really for, straightforwardly". I don't know why that disease is so common, but almost all documentation is like that.
  - deleted 10y ago
    [deleted]
  - greenrd 10y ago
    I think it's because people commonly forget what it's like to be a beginner and which things that are obvious to them are not obvious to a beginner. This is probably more true in Haskell where there is just so much that it's possible to learn that the most advanced Haskell programmers are very, very far ahead of the beginners.
- dualogy 10y ago
  > I'm of the opinion that worked examples are often worse than no documentation. I'm not, especially for the many more-abstract-concepts. I have yet to see a followable code case demonstrating the use of custom monads (not IO or Maybe or lists etc) that show why (when) I should ever write my own, to understand even just using them better generally.. A lot of explanations in the Haskell ecosystem are super-abstract and forever-self-referencing and as someone arriving with a sense of urgency of pumping out Brave New Apps to the world, I'm always itching and saying "OK transformables turn foldables that contain applicatives into functors that fold applicatives into transformables so in other words I CAN SKIP THIS RITE?" Leave it in the shadows as it was clearly a priority to neatly have the abstractions that allowed making MayBe/IO/Lists etc as usable language features in there. On the other hand I don't want to end up writing 10k lines that could have been expressed in 500 had I grasped the more obtuse abstractions. Experience tells me that once you happen across a simple real-world use, the shocking simplicity of what was encrypted in mathematical-logical-calculi lingo is instantly revealed. The absence of such "code examples" (with a real-world touch, not just x,y,z,f,g,h identifiers in a senseless vacuum) is truly annoying and goes all the way from the Wiki to Diehl's articles to various books.. it's hyperprevalent throughout the community.
  - dllthomas 10y ago
    > I have yet to see a followable code case demonstrating the use of custom monads (not IO or Maybe or lists etc) that show why (when) I should ever write my own, to understand even just using them better generally. For an interpreter I'm working on I have an "Eval" type, implemented as a newtype wrapper around a transformer stack. This gives me a context to work in where I can access variables in scope (carried in a ReaderT) and fail with error (handled by an ExceptT). The code (simplified) looks a little like this: {-# LANGUAGE GeneralizedNewtypeDeriving #-} {-# LANGUAGE LambdaExpr #-} newtype Eval a = Eval (Reader EvalContext (ExceptT String m) a) deriving (Functor, Applicative, Monad, MonadReader EvalContext, MonadError String) lookupVariable :: Variable -> Eval Value lookupVariable v = asks (findVarInContext v) >>= \case Nothing -> throwError ("unbound variable: " ++ show v) Just result -> pure result lookupFunction :: FunctionName -> Eval ([Value] -> Value) lookupFunction f = asks (findFuncInContext f) >>= \case Nothing -> throwError ("unknown function: " ++ show f) Just f' -> pure f' evaluateFunction :: Function -> Eval Value evaluateFunction (Function name args) = lookupFunction function <*> mapM evaluateExpr args
- unhammer 10y ago
  I'm one of those who need examples. Fortunately, haddock has this "source" link on each function, so I typically find something usable by browsing through the source of the library I'm using. This takes a lot more time than it would to just have an example in the docs themselves, of course (and isn't always even fruitful). I do notice that after a while, I can get more and more from types alone, but I would never get to that point without examples first. ---- I don't see why examples couldn't be type-checked though, so they never become out-dated – is there no way to do that with haddock?
  - greenrd 10y ago
    Type-checked examples are becoming more popular in the Scala community, e.g. using the tut tool. This is one of the few ways in which the Scala community appears to be ahead of the Haskell community, in terms of technology.
  - sordina 10y ago
    https://github.com/sol/doctest#readme https://github.com/sol/doctest#readme - Very popular.
- mti 10y ago
  > I'm of the opinion that worked examples are often worse than no documentation. That's completely baffling to me so I'd be really curious to hear your reasons (or those of someone who shares that opinion, as there are others in the thread apparently). When learning about an abstract notion, it has been my experience that having good examples in mind (in the sense that they are not too complex, but non-trivial enough to illustrate the relevant aspect of the notion at hand) is very helpful, if not essential, for comprehension. All the more so for very abstract subjects (e.g. back in grad school I was studying algebraic geometry, and you can't go very far in that subject trying to prove things about functors on the category of rings without examples in mind that connect the abstract nonsense to some actual geometric meaning). Speaking of abstract nonsense, by the way, under the Curry-Howard isomorphism, publishing a library with type signatures but no worked out example is equivalent to publishing a mathematical paper consisting entirely of lemmas with no example of how to combine them to prove something interesting (in fact, it's worse, because the expressiveness of the Haskell type system obviously pales in comparison to the language of mathematical papers). I would almost certainly reject a paper like that if I received one for review, and I expect most referees would too.
bojo 10y ago
I'm also in the "I think there is plenty of documentation" camp, so this topic tends to confuse me when it comes up. I suppose what people who are curious about Haskell find lacking are definitive language guides like the Rust Book, Effective Go, and the like?
- zoul 10y ago
  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.
  - 59nadir 10y ago
    Elm was written off because it still does an incredibly bad job at implementing polymorphism. It has a hardcoded "Show" class for turning things into strings and only certain privileged entities can be turned into strings using it. It's all in all a very bad way to do polymorphism and that's what the article points out. It's especially odd in a language like Elm, that obviously is supposed to be like other ML-like languages.
    - zoul 10y ago
      My point is: I tried several times to write something in Haskell, I really want to like the language. But each time I felt too stupid for it, it just feels like too much work. In Elm I got a working app in a day and enjoyed the experience. Isn’t there a lesson for the Haskell community other than “Elm does polymorphism wrong, meh”?
      - eklavya 10y ago
        Maybe both are catering to different programmers?
wyager 10y ago
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.
- dllthomas 10y ago
  I think types are a bit mediocre as documentation. But as you say, mediocre correct documentation beats the pants off of any sort of incorrect documentation. Moreover, it's documentation that's immediately available for the expression I just assembled at the repl! None of which is to say most of us wouldn't love some good, correct documentation. But that takes a lot of effort, and I can see why priorities wind up being elsewhere given that it's a smaller improvement over what's available free than in other languages. Worked examples are actually low-hanging fruit that we really should be making available, given that we can mechanically ensure correctness. Come to think of it, I wonder if this could just be a matter of surfacing existing end-to-end tests somewhere visible.

by moxious 10y ago

chowells 10y ago

Note that it's a contentious issue. Lots of people think there's plenty of documentation. I'm one of them. The people who think documentation is lacking seem to be people who need worked examples of things to understand them. I'm of the opinion that worked examples are often worse than no documentation.

caconym_ 10y ago
I agree. The nature of Haskell and its type system means that the basic haddock docs are already pretty darn useful even without hand-written content (examples, etc.) being included.
barrkel 10y ago
There's research that shows people learn abstractions better when they also have examples. See e.g. [1] for references. However, I find your tone particularly unpleasant. The sneer in "seem to be people who need worked examples of things to understand them" is repulsive. If this is a representative example of your community, it's one no-one should be proud to be a member of. [1] http://www.maa.org/external_archive/columns/launchings/launchings_12_08.html http://www.maa.org/external_archive/columns/launchings/launc...
- mitchty 10y ago
  > However, I find your tone particularly unpleasant. The sneer in "seem to be people who need worked examples of things to understand them" is repulsive. If this is a representative example of your community, it's one no-one should be proud to be a member of. Its always good to apply the principle of good faith. You have no idea who you're talking to, are likely going in biased away from someones arguments, and this will be the first time you've ever conversed. On top of that you're hobbled by text. You also don't know if the writer is a native english speaker or not and might consider the phrase "seem to be people who need worked examples of things to understand them" entirely neutral in tone. Communication is a 2 way street, the tone you perceive may not have been intended. And painting an entire group by one sentence, in one post, that you perhaps disagree with, is a bit of an overreaction in almost any circumstance. The tone you perceive is not one I've personally experienced, quite the opossite. As a beginner in Haskell that is still learning, and learns best by examples, the gp's opinion on documentation drives me nuts. But by and large, most examples aren't all that necessary in haskell with the type system. But when you're learning, I have to say, I hate "the types will document everything" mindset. They tend not to when you're a stranger in a strange land. I wouldn't say documentation itself is a problem in haskell, there is tons. I would say the problem is in quality documentation that at least recognizes audiences of disparate skill level would be at issue. Examples help, but if the examples use something like the state monad that you're not familiar with, it probably won't do you a lick of good to understand how to use it.
  - caconym_ 10y ago
    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.
- efnx 10y ago
  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.
  - moomin 10y ago
    This is only true after you've fully grokked the implications of the types. And, IME, that takes a long time. To give you an example, I spent ages trying to figure out how to create an X. X was a Monad of A. Solution's obvious now...
    - greenrd 10y ago
      Yes, it's a mistake to believe that the type class instances of a type are always going to be advanced details that can be skipped until later. They might be, or they might not.
    - efnx 10y ago
      Examples would help in that case, but there would still be much confusion simply from not understanding Monads (enough to write a computation in that one).
- monkeywork 10y ago
  If that single line is "repulsive" to you maybe you need to re-evaluate your world view a bit.... stop looking for something to be offended about if someone has a differing view
omginternets 10y ago
>I'm of the opinion that worked examples are often worse than no documentation. Counterpoint: this is what keeps me away from Haskell. I really want to learn, and I really do appreciate the formal approach, but being able to do a few simple things quickly (driven mostly by intuition) helps fight frustration. Haskell really does look great, but it's a bit... prickly.
silluk 10y ago
I've been coming back to Haskell sporadically over the past couple of months. Every time I do I find the documentation for things like Prelude to be excellent since that's stuff that I already understand but when trying to dive head-first into a new library I end up with 50 tabs open at various points in the doc to try to keep track of all the different parts. For libraries like megaparsec that have not only great documentation but tutorials and examples available it's often much easier to go in and read the "raw" documentation. Haskell isn't like C++ or other imperative languages in that you don't have "these are the method you can use on this class. Good chance you can figure it out from there". That's why I think that Haskell benefits from good example more than "conventional" languages. Disclaimer: I'm very much a Haskell noobie
- marcosdumay 10y ago
  > Haskell isn't like C++ or other imperative languages in that you don't have "these are the method you can use on this class. Good chance you can figure it out from there". No, but for this case, type holes are much more powerful. You always have an I have X, I want Y, what functions are there that are X -> Y? Hoogle is more powerful than anything I've seen on any other language. (If I could only make it use all the local packages, instead of the pre-built index. I'm sure there's a way.) Haskell has also more need for documentation than most other languages, so hoogle is still not enough. That's the problem, not lack of docs.
sgk284 10y ago
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.
jblow 10y ago
I am a programmer with a lot of experience who has written a lot of things from scratch (not in Haskell). I think most documentation sucks and I dislike trying to read it, because it's very hard to get a picture of what's going on, and what these procedures / data structures / etc are really for. I am much happier when I can just look at a straightforward and clear example, and then just use the documentation to look up specifics of how things work after I already get the basic idea. It's not because I "need worked examples of things to understand them", it's because that is the way I like to work, because I have had many instances of my life of trying to make sense out of documentation that seems to have been written from a mindset of "formal writing involves not actually telling the reader what things are really for, straightforwardly". I don't know why that disease is so common, but almost all documentation is like that.
- deleted 10y ago
  [deleted]
- greenrd 10y ago
  I think it's because people commonly forget what it's like to be a beginner and which things that are obvious to them are not obvious to a beginner. This is probably more true in Haskell where there is just so much that it's possible to learn that the most advanced Haskell programmers are very, very far ahead of the beginners.
dualogy 10y ago
> I'm of the opinion that worked examples are often worse than no documentation. I'm not, especially for the many more-abstract-concepts. I have yet to see a followable code case demonstrating the use of custom monads (not IO or Maybe or lists etc) that show why (when) I should ever write my own, to understand even just using them better generally.. A lot of explanations in the Haskell ecosystem are super-abstract and forever-self-referencing and as someone arriving with a sense of urgency of pumping out Brave New Apps to the world, I'm always itching and saying "OK transformables turn foldables that contain applicatives into functors that fold applicatives into transformables so in other words I CAN SKIP THIS RITE?" Leave it in the shadows as it was clearly a priority to neatly have the abstractions that allowed making MayBe/IO/Lists etc as usable language features in there. On the other hand I don't want to end up writing 10k lines that could have been expressed in 500 had I grasped the more obtuse abstractions. Experience tells me that once you happen across a simple real-world use, the shocking simplicity of what was encrypted in mathematical-logical-calculi lingo is instantly revealed. The absence of such "code examples" (with a real-world touch, not just x,y,z,f,g,h identifiers in a senseless vacuum) is truly annoying and goes all the way from the Wiki to Diehl's articles to various books.. it's hyperprevalent throughout the community.
- dllthomas 10y ago
  > I have yet to see a followable code case demonstrating the use of custom monads (not IO or Maybe or lists etc) that show why (when) I should ever write my own, to understand even just using them better generally. For an interpreter I'm working on I have an "Eval" type, implemented as a newtype wrapper around a transformer stack. This gives me a context to work in where I can access variables in scope (carried in a ReaderT) and fail with error (handled by an ExceptT). The code (simplified) looks a little like this: {-# LANGUAGE GeneralizedNewtypeDeriving #-} {-# LANGUAGE LambdaExpr #-} newtype Eval a = Eval (Reader EvalContext (ExceptT String m) a) deriving (Functor, Applicative, Monad, MonadReader EvalContext, MonadError String) lookupVariable :: Variable -> Eval Value lookupVariable v = asks (findVarInContext v) >>= \case Nothing -> throwError ("unbound variable: " ++ show v) Just result -> pure result lookupFunction :: FunctionName -> Eval ([Value] -> Value) lookupFunction f = asks (findFuncInContext f) >>= \case Nothing -> throwError ("unknown function: " ++ show f) Just f' -> pure f' evaluateFunction :: Function -> Eval Value evaluateFunction (Function name args) = lookupFunction function <*> mapM evaluateExpr args
unhammer 10y ago
I'm one of those who need examples. Fortunately, haddock has this "source" link on each function, so I typically find something usable by browsing through the source of the library I'm using. This takes a lot more time than it would to just have an example in the docs themselves, of course (and isn't always even fruitful). I do notice that after a while, I can get more and more from types alone, but I would never get to that point without examples first. ---- I don't see why examples couldn't be type-checked though, so they never become out-dated – is there no way to do that with haddock?
- greenrd 10y ago
  Type-checked examples are becoming more popular in the Scala community, e.g. using the tut tool. This is one of the few ways in which the Scala community appears to be ahead of the Haskell community, in terms of technology.
- sordina 10y ago
  https://github.com/sol/doctest#readme https://github.com/sol/doctest#readme - Very popular.
mti 10y ago
> I'm of the opinion that worked examples are often worse than no documentation. That's completely baffling to me so I'd be really curious to hear your reasons (or those of someone who shares that opinion, as there are others in the thread apparently). When learning about an abstract notion, it has been my experience that having good examples in mind (in the sense that they are not too complex, but non-trivial enough to illustrate the relevant aspect of the notion at hand) is very helpful, if not essential, for comprehension. All the more so for very abstract subjects (e.g. back in grad school I was studying algebraic geometry, and you can't go very far in that subject trying to prove things about functors on the category of rings without examples in mind that connect the abstract nonsense to some actual geometric meaning). Speaking of abstract nonsense, by the way, under the Curry-Howard isomorphism, publishing a library with type signatures but no worked out example is equivalent to publishing a mathematical paper consisting entirely of lemmas with no example of how to combine them to prove something interesting (in fact, it's worse, because the expressiveness of the Haskell type system obviously pales in comparison to the language of mathematical papers). I would almost certainly reject a paper like that if I received one for review, and I expect most referees would too.

bojo 10y ago

I'm also in the "I think there is plenty of documentation" camp, so this topic tends to confuse me when it comes up. I suppose what people who are curious about Haskell find lacking are definitive language guides like the Rust Book, Effective Go, and the like?

zoul 10y ago
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.
- 59nadir 10y ago
  Elm was written off because it still does an incredibly bad job at implementing polymorphism. It has a hardcoded "Show" class for turning things into strings and only certain privileged entities can be turned into strings using it. It's all in all a very bad way to do polymorphism and that's what the article points out. It's especially odd in a language like Elm, that obviously is supposed to be like other ML-like languages.
  - zoul 10y ago
    My point is: I tried several times to write something in Haskell, I really want to like the language. But each time I felt too stupid for it, it just feels like too much work. In Elm I got a working app in a day and enjoyed the experience. Isn’t there a lesson for the Haskell community other than “Elm does polymorphism wrong, meh”?
    - eklavya 10y ago
      Maybe both are catering to different programmers?

wyager 10y ago

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.

dllthomas 10y ago
I think types are a bit mediocre as documentation. But as you say, mediocre correct documentation beats the pants off of any sort of incorrect documentation. Moreover, it's documentation that's immediately available for the expression I just assembled at the repl! None of which is to say most of us wouldn't love some good, correct documentation. But that takes a lot of effort, and I can see why priorities wind up being elsewhere given that it's a smaller improvement over what's available free than in other languages. Worked examples are actually low-hanging fruit that we really should be making available, given that we can mechanically ensure correctness. Come to think of it, I wonder if this could just be a matter of surfacing existing end-to-end tests somewhere visible.