3 ms·

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_probl

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

by bojo 10y ago

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.