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
MkDocsand theMaterialtheme, 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.
)