Haskell Guide (cross posted on reddit)

I’ve recently been working on a Haskell Guide, aimed at newcomers with experience in Python or similar. See here: https://haskell-docs.netlify.app/

It’s a work in progress, but as it’s become fairly sizable, I wanted to share it. If people like it, they’re warmly encouraged to submit PRs for improvements, or ask to be added to the repo as collaborators!

Since there are quite a lot of attempts to write Haskell introductory material, with varying levels of success (and some understandable scepticism), I’ve included some notes about why I think this guide is a Good Idea.

Motivation

Chris Allen has some really nicely written thoughts on the variety of existing newcomer-facing resources (as of a few years ago), and what he thinks of each. Having co-written one of the best books on Haskell, he’s well positioned to comment.

I suspect he would not love this project because:

  • it deliberately has no exercises and (currently) lacks depth (e.g. detailed examination of performance implications of purity, immutability, or laziness)
  • it puts a lot of value on aesthetics, both in the sense of looking pretty, and having a lot of visual cues, cross-referencing links and marked up code snippets.

Anticipating (friendly) criticisms of that nature, I think it’s worth identifying a difference in goals.

The goal here isn’t to provide the best possible pedagogical experience for a determined newcomer to Haskell who is ready to spend money and who has lots of time and effort to spare.

Rather, the goal is to be useful to newcomers who may not have the inclination to invest a lot of time and effort, and to document clearly but concisely what Haskell is like, for a reader with those constraints.

For example, if I had a friend who coded in Python and I wanted to persuade them to try out Haskell, I might be a bit reluctant to recommend a book, but would want to share (the ideal future version of) this guide with them. Or if I saw a beginner question on Reddit, and wanted to refer to a known FAQ or gotcha, I might use this guide. Or if I had a coworker who knew some functional programming (e.g. from Python’s functools) but I wanted to get them up to speed in Haskell, I might use it.

From the perspective of this goal, here are some features that I think are good (but not all unique):

  • free and online
  • sections for Gotchas and FAQs
  • visually pleasing, thanks to MkDocs and the Material theme, and its many great features: code annotations, code snippets, fancy search functionality, info boxes, tabs, sections and internal links help reduce the reader’s cognitive load (MkDocs Material is extremely well-designed, well-documented, and feature-rich)
  • holistic: up-to-date information to install Haskell + tooling, links to external resources, explanation of what a project looks like, and an example project as a case study with comments and discussion
  • documentation-style arrangement of material, with heavy cross-referencing: designed to appeal to readers who want to decide the level of depth they want to engage at
  • neutral prose style and name (compare to the more whimsical “Learn You a Haskell”)

Pushing for collaboration

The other goal is to be, above all else, easy for anyone to edit, with a style guide (to be expanded), and a modular design that lends itself to constant small improvements, so that in the longer term, this guide becomes very polished.

In fact, a few people have already contributed corrections and improvements PRs, and I’d really love that trend to continue.

(Anticipating the objection that the Haskell wiki is also easy to edit, I’d add that it serves a different purpose, as a much less curated resource, and more of a valuable repository of miscellaneous information about Haskell)

In conjunction, I’d like it to be easy for readers to ask technical questions, and I think the current comments system, which requires a github account, should minimize spam.

15 Likes

Pretty good overall. What is the license though? It does not seem to have one, so that would be proprietary, in which case would be a disservice to any contributor other than yourself. So I would suggest using GNU AGPL for the software, and dual license the text with GNU FDL and CC BY-SA 4.0. I think it would be pretty good to have something like that, or that, officially on the Haskell website; akin to the Rust book The Rust Programming Language - The Rust Programming Language.

1 Like

Thanks for the feedback! I don’t know anything about licenses, so your advice is useful. The underlying software is MkDocs Material, which has this license. Would you recommend I just copy that page, perhaps with the licenses you recommend above for the text? (Also feel free to add via PR :slight_smile: )

1 Like

There are 2 main types of free licenses: copyleft (share derivative works or copies with same license), permissive (allow sublicensing/relicensing derivative works/copies). The license you linked, MIT, is permissive, generally used for software. A better permissive license is the Apache License, Version 2.0, because it protects against entities appropriating the work to themselves through patents. If you want, you can dual-license Apache and MIT just like the rust book (book/LICENSE-APACHE at main · rust-lang/book · GitHub, book/LICENSE-MIT at main · rust-lang/book · GitHub). GHC itself is licensed under the permissive 3-Clause BSD License. In my opinion, copyleft licenses are fundamentally better because it obligates any entities that modify the work to only redistribute it under the same license, protecting both users and contributors rights in a stronger way. GNU has the best copyleft licenses. The creative commons I had linked is good for text/art.

I recommend reading

1 Like

I like the guide and have just successfully followed the installation steps on one of my Windows laptops. But stubborn and impatient Windows users like me need to be more pointedly reminded to first check to see if msys is installed and, if not, then go to msys2.org and do the download and installation before starting the ghcup installation process. Thanks and good work!

Si Dunn
Austin, TX

2 Likes

GHCup should install msys for you if it is not installed already.

4 Likes

This is really well written so far, quite understandable for me who knows a smidgeon of Haskell now, knows decent fp via other languages, but want to start building something sizable with Haskell.

If you keep a specific audience (maybe my level of proficiency?) in mind, this can grow to be something really useful.

2 Likes

@sidunn Thanks for the feedback! I’ll defer to @jaror’s comment here, but happy to update the instructions, or include special instructions for windows if the consensus is that this is necessary.

@yuu Thanks for your advice! I’ve now included the GNU FDL, as per your advice.

@dangdennis Thank you, this is encouraging! The specific audience that I’d like to target is Python programmers (or similar), so people who have heard of map (or at least, know about list comprehensions) and have heard of types, but aren’t yet functional programmers. Let me know the areas where you’d like to see more content, and of course feel free to give low-level feedback as you use the guide re. what is clear/unclear.

1 Like