Updating the Documentation page #189
Comments
|
This is great stuff, thank you for putting it together. I will come back and help flesh out these ideas at some point in the near future. |
|
Thanks! There are also some downstream tasks that are connected to this that also occurred to me, such as:
|
Consider this: LYAH has been the most popular Haskell book in the past 10 years, and Haskell is still known to be very difficult to learn, so maybe putting LYAH front and center isn't exactly going to help the Haskell on-boarding experience? |
|
Some more comments: I think it's important to recognize that there are many different kinds of people who might be interested in Haskell, such as:
...and so on. I don't think there's no one size fits all here - these groups likely want different things from Haskell and a getting started guide that is tailored to one group will probably make it harder for the other groups. For example, I think that the industrial programmer will benefit from reading cs240h basics more than from reading LYAH, and the academic might benefit more from reading the Haskell report. Most of them will probably be interested in a super quick tour to what Haskell looks like. Another example: should the getting started page mention category theory? For the math enthusiasts and academics, probably yes! For the industrial programmers? There's a common conception that to use Haskell you must learn category theory. Maybe this will enforce the wrong impression that category theory is a must which will drive some people away? In short, the target audience for the getting started page should be clear. Might even be worth considering making multiple getting started pages depending on the audience you'd like to cater to.
Do note that not being able to use Haskell to build things is not a sign of an advanced Haskeller, but of a beginner. A first learning resource should take care of that (even if some of them don't...). The way I see it an advanced Haskell is one who can already build stuff with Haskell, but is interested in getting more out of it with more specific things like reducing boilerplate, improving correctness/static guarantees, improving performance, wrapping C libraries, etc.
I think WIWIK can be overwhelming rather then friendly. It is a very useful piece, especially for learning specific things or searching for an answer to a question, but I think this phrasing presets it as an article to read.
This is kind of related to fp complete's haskell page. I think it's a good idea in general, though maybe in a separate page. I also think that a section of beginner friendly project-based tutorials (for example a website, a game, a compiler, etc) can be very useful. I would also mention the haskell phrasebook. |
|
Thanks, this is really useful feedback. The point about the different groups coming to Haskell is well-taken, but here's my thinking. I'm less worried about groups 1 and 4: academics will be more familiar with the motivations for Haskell and less concerned about its differences to conventional languages used in industry. Programmers interested in intellectual challenges will probably be willing to do their own research into resources too. It's groups 2 and 3 that I think a learning page on haskell.org should principally target, basically to lure them in (or at least avoid repelling them). That's true re. LYAH. Maybe that detail could be changed to cs240h or similar, or one of the many other Haskell intro books. Or LYAH could be offered as a resource for people with less experience programming. Maybe "Advanced" could be substituted (copying the Rust page here) for "Grow with Haskell" and the actually advanced features could be "Master Haskell". Re WIWIK, that's a great point too. I hadn't seen the Haskell phrasebook, it's nice too. One thing I'm aware of is that there are many many good resources, but my thinking is that it's best to pick a small subset, so that subsequent attention can be given to making sure those are as good as possible and kept up to date (again see the Rust page). I'm envisioning a virtuous cycle where a small set of great resources get maintained and improved over time. |
LYAH has not been recommended by us IRC users for a long time, mainly because it doesn't have any exercises and is not considered an in-depth resource. So I'm strongly -1 on that specific idea. Also note that ghcup now has a "getting started" page with links to proper learning materials: https://www.haskell.org/ghcup/steps/ |
|
Thanks again to @reubenharry for putting this together and @soupi for @hasufell for the comments. The point about LYAH is pretty compelling to me. Personally I've never read it, but I understand what @soupi means: if so many people have tried it, yet Haskell still has this reputation as "hard to learn", then can it really be such a great introduction? There must be better materials for explaining Haskell. @bitemyapp's "How should I learn Haskell guide" is tried and tested, I think. I personally don't have time to drive this forward or even participate much, but I think that converting the "Documentation" page to be somewhat more opinionated is a good idea. It will take time to do work out the exact contents and do the necessary consensus-building in the community, but it will be worthwhile I think. |
|
I would advise @reubenharry to keep going, keep iterating and responding to feedback, and hopefully the result will be something will be a nicely polished page, or introduction to Haskell learning resources, and we can look at incorporating it on the site. |
|
Sounds good. I've started updating the above markdown draft, and will continue. I left LYAH in for now, because it is the only free intro book I'm aware of (Real World Haskell being somewhat out of date) and I at least can attest to having learned the basics of Haskell from it, though I agree that it is flawed. FP Complete has a bunch of really useful materials, but I assume there are political issues with incorporating those materials with haskell.org? Hopefully not |
https://github.com/haskell-beginners-2022/course-plan https://www.cis.upenn.edu/~cis194/spring13/ As linked by https://www.haskell.org/ghcup/steps/#how-to-learn-haskell-proper These are real learning materials. |
|
OK, I removed LYAH, by way of compromise :) And since the rest of the books were either not for beginners or not free, I took them out too. (What I removed is below) Learn You a Haskell is a friendly place to start if you're new to programming. There's also a notebook version if you like to learn interactively. Other intro Haskell books (click to expand) |
|
I think it is wrong to remove the books entirely from the documentation page. Even though some of the books are paid, they are invaluable resources and they should be listed. Additionally, it is worthwhile to list even the intermediate ones, if they are marked as such. I'm fine with not steering users to them as a first stop, but to remove them altogether will have a bad effect. I also think the haskell wikibook is fine to refer people to. In general, the material which is on the page and is removed in this PR (not just books) is good material and worthwhile to keep around. Highlighting a "getting started" section that has a few recommended tutorials, and is opinionated and steers people is a good thing. I like the idea behind it! However, below that section, or on another page, a more comprehensive list of resources would also be very worthwhile. If people found it more difficult to find e.g. the cabal users guide or the typeclassopedia, or marlow's wonderful book on concurrency, or bird's "thinking functionally in haskell" etc., then that would be a real shame. |
|
A general proposal would be that this material go under "Learning Haskell" at the top of the page (and the links not just say "this documentation" or "this article" but name the cited resource) but below it there's an "Additional Documentation" section that keeps all the existing resources. The fact that there's a bunch of actual paid print books about Haskell is a good thing -- some people want them, and it speaks to the quality and scope of the resources available. If that information is not easy to come by, it substantially undersells the language and the material available. |
I agree, and I think that probably the smoothest approach would be to create an entirely new page called something like "Learn Haskell" or "Start your Haskell journey" and keep the Documentation page as it is. |
It's not really documentation. It's a dump of links. That may be useful, but is not what anyone expects of documentation. |
|
@gbaz I agree that many of the books I removed are very valuable resources that people should definitely have access to. I should emphasize that what I'm advocating is basically what @tomjaguarpaw is saying, which is to make a "Learn Haskell" page with a highly directed set of resources, rather than exposing people to all good resources out there. Having a larger and more complete listing of all good resources is also nice, but as @hasufell says, that isn't really what the current Documentation page is doing. In fact, doing that well seems like a much larger task, where a large subset of the really high quality resources (books and online articles) are carefully sorted and presented. What I'm proposing is more of a short term easy improvement, which is to take the current documentation page (that I think is too unstructured) and turn it into a "Learn Haskell" page that serves to orient newcomers. I think that would be a net improvement to the Haskell website. As a compromise, I could add the books as Further Resources at the bottom though. |
|
Removing a bunch of useful stuff and not putting it somewhere else is not an improvement. I support creating an upfront section with a "learn haskell" focus. I oppose removing links to resources that don't fit there. They should either be kept on the same page as a lower section, or moved to another easily accessible page. (here i am not referring simply to books but to all the links that this pr eliminates to useful resources). |
|
OK, that's fair enough, I'll update the above to either preserve those links at the bottom or link to them. I should say that what I'm concerned about is that having a large dump of links is somewhat overwhelming, and if links are broken (which as far as I know, no-one is in charge of checking) it gives a really bad impression of the Haskell page. |
All links are checked, both external and internal, on every CI run: www.haskell.org/.github/workflows/main.yml Lines 35 to 42 in 089dd67 |
|
OK, after a bit of thinking, I think you're right that what I'm proposing shouldn't be in replacement of the Documentation page, but in addition. I think what I really want is a "Getting Started" page that recommends a toolchain, links to a single tutorial, and explains the library system (hackage and hoogle, and an overview of which libraries are for what). (As well as that, I think the current frontpage of haskell.org should have more propaganda on why to use Haskell, but that's a separate issue.) Separately, I think the current documentation page isn't adding a huge amount of value in its current state. I think having a page with lots of links is useful, but actually not as useful as it might seem, because people are comfortable with using google. For example, anyone who wants a Haskell book can google "Haskell books" and pick one that looks good to them. I'd prefer to see slightly fewer links, with more explanation of each link. In that vein, a link to Hackage and Stackage with no context is not that useful if you don't know how to use them. But improving this is a lot of hard work. I'll step back and think how I can update the above proposal to make it a "Get started" page, and not a replacement for the Documentation page. |
This issue is somewhat related to #61 and #136 and the more general goal of making the Haskell "on-boarding" experience smooth. See also this discussion on the Haskell discourse page: https://discourse.haskell.org/t/rfc-documentation-overhaul-on-haskell-org/1942
Below is a suggested new version of the current Documentation page (https://www.haskell.org/documentation/). I don't have any web design skills, so am just presenting it as Markdown, which is not to say that a fancier layout wouldn't look better. The general philosophy is to present fewer options, so that there's a clearer, more centrally endorsed pathway of what to look at, and less chances of broken links. The equivalent Rust page (https://www.rust-lang.org/learn) seems to me like something to aim for (Julia's one - https://julialang.org/learning/ - feels a bit cluttered IMO).
I'm assuming that the Get Started instructions would be elsewhere (i.e. a link to GHCUP on the front page, along with clear setup instructions for HLS with VSCode, which should be the community endorsed standard IDE).
Beyond updating the page, I think the following ought to happen:
This is intended as a draft, not a complete version. The idea is to get a sense of whether people think this is
a) generally a good idea, but disagree with the specifics
b) bad idea, makes things worse, but thanks for the suggestions!
c) good idea, and here are some further suggestions
Learning Haskell
The online course from UPenn goes from the basics, and is thorough and clear. (Homework optional!)
Other courses and tutorials (click to expand)
Using Haskell libraries
Search for functions by name, package or by their type signatures with Hoogle
Find package source code on Hackage, the central package archive for Haskell. Packages are typically documented with marked up source code comments, known as Haddock
Reference materials
Familiarize yourself with important Haskell concepts and features with this reference
Learn standard style conventions from this guide
Understand what areas of programming Haskell excels in, and what libraries to use from this overview of the ecosystem
Behind the curtain
Understand the internals of Haskell's powerful compiler, GHC, from this documentation
Understand the full specification of Haskell from the language report
The text was updated successfully, but these errors were encountered: