Repository navigation
Improve ordering of content #340
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
Maybebefore ADTs,Unitwith no explanation,donotation andpurewithout discussingbindand 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.
Activity
klarkc commentedon Sep 1, 2021
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 #303)
Refactor Ch4 largestSmallest using pattern matching to improve readab…
Refactor Ch4 largestSmallest using pattern matching to improve readab…
Zelenya commentedon Jul 10, 2023
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
Context
Current topics
Current/open issues
whereindentation [Ch3] Indentation docs forwhereare wrong #397flipto Chapter 4 with more description and new repl output Chapter 3 - repl print out for "flip" needs updating? #326 Better explanation of flip function #260Unitwith no explanation Improve ordering of content #340donotation andpurewithout discussingbindand related typeclasses. Improve ordering of content #340Chapter 4. Exercise. countEven wants (future topic) pattern matching Ch4 - Is it possible to solve the countEven exercise without pattern matching? #303Solved by chapter 4-5 swapChapter 4. Cover ADTs (andMaybe) beforedonotation Ch4 Defer Array do notation section #212Partially handled by the swap and prev. issuecombineListandsequenceCh7 Align definitions ofcombineListandsequence#155Either eCh8 - ClarifyEither e#162