Description
Some of the book's content is presented in a non-ideal sequence which frustrates beginners in the following ways:
- We present exercises that cannot be solved idiomatically using only the material covered so far - and even worse, is that some of our reference solutions use techniques that are only covered in later chapters.
- We refer to stuff that has not been explained yet. Chapter 4 is a pretty bad offender (references
Maybe
before ADTs,Unit
with no explanation,do
notation andpure
without discussingbind
and related typeclasses).
One simple improvement is to cover pattern matching (ch5) before recursion (ch4) (highlighted in #303). We should also cover ADTs (and Maybe
) before do
notation (proposed in #212).
But I think the book would really benefit from a more systematic restructuring where we do something like the following:
- Create a list of all topics we want the book to cover.
- Identify which topics depend on other topics.
- Create new (or classify existing) exercises for each topic and note what other prerequisites are required for writing idomatic solutions.
- Assemble these topics in the book where we're respecting all prerequisites.
We could also push more of these topic explanations to other language reference locations (e.g. docs repo and library docs), then link to those from the book. That way, the book will serve more as a guide on learning sequence with accompanying exercises to avoid duplicating content.
I think there would also be value of distinguishing a minimum set of "core" concepts that all users must know (e.g. functions, ADTs, typeclasses, etc. - noted in https://discourse.purescript.org/t/guide-to-learn-purescript/2308/4) from the supplemental topics (e.g. generative testing, canvas graphics). This could be noted in the book's introduction.