6 ms·

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 abou

by 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?
      - 8fGTBjZxBcHq 10y ago
        Is Haskell catering to programmers who don't want to be able to get a simple app up in a day? Who are these programmers who fight through the first steps of picking up a language and are thrilled by that.
        eklavya 10y ago
        Maybe yes, You can not learn Haskell in one day, if that was your point. My point is learning Haskell takes time and it's hard and it is totally understandable if for some people that is not a good investment.
- bojo 10y ago
  To be fair this thread is an example of the Haskell community agreeing with you: https://www.reddit.com/r/haskell/comments/2ory86/there_is_a_documentation_problem_stop_pretending/ https://www.reddit.com/r/haskell/comments/2ory86/there_is_a_... (2014) After using the language for two years I find that the types are actually enough to understand a new library, however, am taking for granted that it's an acquired skill. Looking back I do recall being in the same position as you, someone who just wanted to wrap their head around something and get an example working. I was stubborn and plowed through things I didn't understand until it clicked, but do realize that not everyone is as hard headed as myself.
  - pronik 10y ago
    As a recent beginner, I've found it incredibly hard to write something practical by putting a library into good use. If you want more that printing out Fibonnacci sequences, like printing out your own Twitter stream, like I have done, you better be ready for a lot of pain. The twitter module makes extensive usage of lens, wraps everything with conduit (at least within the examples). Conduit itself is exhaustively documented, as are lens, but you can't get started without a couple of external tutorials, since there is no practical description of the basic underlying concepts in the main documentation on hackage. And even then you don't know exactly how everything fits in, since all you get is for the most part what, but not how and especially why you should be using this what. So my basic impression is: as soon as you know where the library fits in and how it works and even more importantly why it is doing things the way it does, you can get by just by using type signatures. But that knowledge is usually hidden behind a myriad of half-done blog posts and well-meant tutorials, which introduce you to the what but still assume a good deal of knowledge about why. And the rabbit hole gets larger with every dependency boiled onto your actual study target. It's not by any means impossible to get in, but I think it could get a lot better. Just making a habit of merging tutorials and introductions into the module's documentation would be a great step forward. A mandatory ELI5 section might do wonders :)
  - rpglover64 10y ago
    > After using the language for two years I find that the types are actually enough to understand a new library, however, am taking for granted that it's an acquired skill. I think this overstating it, unfortunately. I'm an intermediate Haskeller, and when I tried to use `hasql`, I found the lack of documentation to slow me down. It's a testament to the power of types as documentation that I was able to use it at all, but examples and simple cookbook-style "Here's how you do this thing" or "Here's how you use this component" or "You can't do this because the interface doesn't allow it; here's why" would have sped up my acquisition of the library immensely.
- s_kilk 10y ago
  > I stress that the types are not enough Exactly. Quick, tell me what this function does: foo :: Num a => a -> a
  - pronik 10y ago
    It foos a number into another number, what else? If it does something else or if it's unclear what fooing is, it should be renamed and the parameter types should be at least aliased to something more adjusted to the task. It's basically Haskell code smell. Other languages we are used to do not allow exact precision when talking about input and output types, that's why we don't think about overly-generic function declarations as smelly, but they are.
    - auggierose 10y ago
      That's typical Haskell brain wash talk. Types can be a useful part of the documentation, but if your program is the least bit interesting, you will have parts that you should properly document. This is so much more true for libraries, especially those that adhere to a more mathematical style. If you write such a library, you should also write a paper explaining the library.
    - deleted 10y ago
      [deleted]
    - icebraining 10y ago
      Just out of curiosity, how would you change the following definition to make sure it's clear without reading anything else? words :: String -> [String] If you say it's already obvious, I disagree, since this code prints "1": main = print $ length $ words "jack am I" (The spaces in the string are six-per-em unicode characters)
      - pronik 10y ago
        (like I said elsewhere, I'm a beginner, so I might be over-euphorical about controversial ideas. Also I don't in any way propose working only with type definitions instead of prosa documentation, however I think type definitions can go a long way to introduce the basic operations to the user) In this case, I'd try something like this: words :: Sentence -> [Word] (Sentence and Word being aliases for String) A function named `words` with `Sentence` as a parameter implies a common-sense do-what-I-mean function, like breaking on all sensible whitespace. With common sense in play, it's your task to make the function behave like people expect it to (which differs per person of course). If you choose not to, don't write `words`, write a `split` with a parameter for character classes (or indeed a boolean function working on a character) the split should be performed on. (PS. I assume you are implicitely critisizing Prelude's `words`, which breaks on anything that's `isSpace`, which is explicitely defined. Its definition is way out of my competence, there are probably good reasons for not including thin spaces. If not, they could probably get included with a due process -- with common sense, it's always an iterative process till it's done)
- mightybyte 10y ago
  I was writing a reply to this, but it got long enough that I decided to make it a standalone blog post. http://softwaresimply.blogspot.com/2016/12/on-haskell-documentation.html http://softwaresimply.blogspot.com/2016/12/on-haskell-docume...
  - bojo 10y ago
    I was considering writing roughly the same thing you did, thanks. There's a lot of terrible documentation in every language, but I think it may be a losing battle to show this as a counter example unfortunately. I think it's just that the gap to get proficient with Haskell for an imperative programmer is a hurdle they are blind to (I was blind myself!), and they assume a few simple tutorials will bootstrap them into the language like it did the other handful they learned. This is clearly an education problem, but I guess we still have a ways to go to get acceptance.
    - mightybyte 10y ago
      > I think it may be a losing battle to show this as a counter example unfortunately. Yeah, my intent wasn't to suggest that all non-haskell docs suck. But to show how other languages are much more howto/tutorial oriented, which I didn't appreciate as much before I had to look at ACE recently.
marcosdumay 10y ago
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.

by bojo 10y ago

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?
    - 8fGTBjZxBcHq 10y ago
      Is Haskell catering to programmers who don't want to be able to get a simple app up in a day? Who are these programmers who fight through the first steps of picking up a language and are thrilled by that.
      - eklavya 10y ago
        Maybe yes, You can not learn Haskell in one day, if that was your point. My point is learning Haskell takes time and it's hard and it is totally understandable if for some people that is not a good investment.
bojo 10y ago
To be fair this thread is an example of the Haskell community agreeing with you: https://www.reddit.com/r/haskell/comments/2ory86/there_is_a_documentation_problem_stop_pretending/ https://www.reddit.com/r/haskell/comments/2ory86/there_is_a_... (2014) After using the language for two years I find that the types are actually enough to understand a new library, however, am taking for granted that it's an acquired skill. Looking back I do recall being in the same position as you, someone who just wanted to wrap their head around something and get an example working. I was stubborn and plowed through things I didn't understand until it clicked, but do realize that not everyone is as hard headed as myself.
- pronik 10y ago
  As a recent beginner, I've found it incredibly hard to write something practical by putting a library into good use. If you want more that printing out Fibonnacci sequences, like printing out your own Twitter stream, like I have done, you better be ready for a lot of pain. The twitter module makes extensive usage of lens, wraps everything with conduit (at least within the examples). Conduit itself is exhaustively documented, as are lens, but you can't get started without a couple of external tutorials, since there is no practical description of the basic underlying concepts in the main documentation on hackage. And even then you don't know exactly how everything fits in, since all you get is for the most part what, but not how and especially why you should be using this what. So my basic impression is: as soon as you know where the library fits in and how it works and even more importantly why it is doing things the way it does, you can get by just by using type signatures. But that knowledge is usually hidden behind a myriad of half-done blog posts and well-meant tutorials, which introduce you to the what but still assume a good deal of knowledge about why. And the rabbit hole gets larger with every dependency boiled onto your actual study target. It's not by any means impossible to get in, but I think it could get a lot better. Just making a habit of merging tutorials and introductions into the module's documentation would be a great step forward. A mandatory ELI5 section might do wonders :)
- rpglover64 10y ago
  > After using the language for two years I find that the types are actually enough to understand a new library, however, am taking for granted that it's an acquired skill. I think this overstating it, unfortunately. I'm an intermediate Haskeller, and when I tried to use `hasql`, I found the lack of documentation to slow me down. It's a testament to the power of types as documentation that I was able to use it at all, but examples and simple cookbook-style "Here's how you do this thing" or "Here's how you use this component" or "You can't do this because the interface doesn't allow it; here's why" would have sped up my acquisition of the library immensely.
s_kilk 10y ago
> I stress that the types are not enough Exactly. Quick, tell me what this function does: foo :: Num a => a -> a
- pronik 10y ago
  It foos a number into another number, what else? If it does something else or if it's unclear what fooing is, it should be renamed and the parameter types should be at least aliased to something more adjusted to the task. It's basically Haskell code smell. Other languages we are used to do not allow exact precision when talking about input and output types, that's why we don't think about overly-generic function declarations as smelly, but they are.
  - auggierose 10y ago
    That's typical Haskell brain wash talk. Types can be a useful part of the documentation, but if your program is the least bit interesting, you will have parts that you should properly document. This is so much more true for libraries, especially those that adhere to a more mathematical style. If you write such a library, you should also write a paper explaining the library.
  - deleted 10y ago
    [deleted]
  - icebraining 10y ago
    Just out of curiosity, how would you change the following definition to make sure it's clear without reading anything else? words :: String -> [String] If you say it's already obvious, I disagree, since this code prints "1": main = print $ length $ words "jack am I" (The spaces in the string are six-per-em unicode characters)
    - pronik 10y ago
      (like I said elsewhere, I'm a beginner, so I might be over-euphorical about controversial ideas. Also I don't in any way propose working only with type definitions instead of prosa documentation, however I think type definitions can go a long way to introduce the basic operations to the user) In this case, I'd try something like this: words :: Sentence -> [Word] (Sentence and Word being aliases for String) A function named `words` with `Sentence` as a parameter implies a common-sense do-what-I-mean function, like breaking on all sensible whitespace. With common sense in play, it's your task to make the function behave like people expect it to (which differs per person of course). If you choose not to, don't write `words`, write a `split` with a parameter for character classes (or indeed a boolean function working on a character) the split should be performed on. (PS. I assume you are implicitely critisizing Prelude's `words`, which breaks on anything that's `isSpace`, which is explicitely defined. Its definition is way out of my competence, there are probably good reasons for not including thin spaces. If not, they could probably get included with a due process -- with common sense, it's always an iterative process till it's done)
mightybyte 10y ago
I was writing a reply to this, but it got long enough that I decided to make it a standalone blog post. http://softwaresimply.blogspot.com/2016/12/on-haskell-documentation.html http://softwaresimply.blogspot.com/2016/12/on-haskell-docume...
- bojo 10y ago
  I was considering writing roughly the same thing you did, thanks. There's a lot of terrible documentation in every language, but I think it may be a losing battle to show this as a counter example unfortunately. I think it's just that the gap to get proficient with Haskell for an imperative programmer is a hurdle they are blind to (I was blind myself!), and they assume a few simple tutorials will bootstrap them into the language like it did the other handful they learned. This is clearly an education problem, but I guess we still have a ways to go to get acceptance.
  - mightybyte 10y ago
    > I think it may be a losing battle to show this as a counter example unfortunately. Yeah, my intent wasn't to suggest that all non-haskell docs suck. But to show how other languages are much more howto/tutorial oriented, which I didn't appreciate as much before I had to look at ACE recently.

marcosdumay 10y ago

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.