search

purescript-contrib / purescript-book

Sources for the PureScript book
https://book.purescript.org/
360 stars 194 forks source link

Improve ordering of content #340

Open milesfrain opened 3 years ago

milesfrain commented 3 years ago

Some of the book's content is presented in a non-ideal sequence which frustrates beginners in the following ways:

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:

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.

klarkc commented 3 years ago

I just found this case right here. I was reviewing the solutions that were made to compare to my solutions, and did not expected a pattern matching solution that only appears on the next chapter. Worth mentioning that my solution did not use pattern matching, of course. (duplicated https://github.com/purescript-contrib/purescript-book/issues/303)

Zelenya commented 1 year ago

I did a pass through the issues collecting all the suggestions and through code gathering the topics.

TLDR. I don’t think we need to redo or move a lot of stuff around. I propose a few swaps (for example, swap chapters 4 and 5) and then extend content based on the existing (or future) issues and confusions.

Additionally, I’d like to break (some) chapters into subchapters to make it easier to navigate and digest. (see Rust book

Note that I’ve been focusing on content – not exercises; I think these could be added ad-hoc afterwards.

Context

Current topics

Current/open issues