Repository navigation
Improve ordering of content #340
Description
Activity
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)
- added a commit that references this issue
on Sep 26, 2021 - added a commit that references this issue
on Oct 3, 2021 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
- Chapter 3. Functions and Records
- Types
- Quantified Types
- Indentation
- Records
- Type Constructors
- Kinds
- Functions
- Curried Functions
- Infix Function Application
- Function Composition
- Chapter 4. Recursion, Maps, And Fold
- (uses maybes, while they are introduced in chapter 5)
- Recursion
- Map and filter
- Array Comprehensions
- Do Notation
- Folds
- Tail Recursion
- Chapter 5. Pattern Matching
- Pattern Matching
- Array Patterns
- Row Polymorphism
- Record Puns
- Algebraic Data Types
- Newtypes
- Chapter 6. Type Classes
- Show, Eq, Ord, Field
- Semigroups, Monoids, Foldable
- Functor
- Deriving Instances
- Type Class Constraints
- Multi Parameter Type Classes
- Functional Dependencies
- Superclasses
- Chapter 7. Applicative
- Applicative
- Traversable
- Chapter 8. Effect
- Monad
- Side-Effects and Purity
- Exceptions
- Mutable State
- DOM Effects
- Chapter 9. Asynchronous Effects
- Aff
- Parallel Computations
- Chapter 10. The Foreign Function Interface
- Asynchronous Functions
- JSON
- Calling PureScript from JavaScript
- Chapter 11. Monads
- State
- Reader
- Writer
- Monad Transformers
- mtl
- Alternatives
- Chapter 12. Canvas Graphics
- Chapter 13. Testing
- Chapter 14. Domain-Specific Languages
Current/open issues
- Update intro updating introduction, mostly links, see #173 #193 Update Introduction #173
- Recheck all the repl type-outputs
- Add a note on constraints when they first pop-up in the repl signature (type-classes come late, the type-signatures shouldn’t be super mysterious until then)
- Drop type class instance names
- Chapter 6 should still have a note on naming
- Swap Chapter 4 and Chapter 5 Improve ordering of content #340
- Chapter 3. Fix notes on
whereindentation [Ch3] Indentation docs forwhereare wrong #397 - Chapter 3. Move
flipto Chapter 4 with more description and new repl output Chapter 3 - repl print out for "flip" needs updating? #326 Better explanation of flip function #260 - Chapter 3. Improve curried functions and partial application Ch3 - Improve content on curried functions and partial application #261
- Chapter 4.
Unitwith no explanation Improve ordering of content #340 - Chapter 4.
donotation andpurewithout discussingbindand related typeclasses. Improve ordering of content #340- Explain abstractions vs concrete map, pure, etc.
- Reference/Cover it later in the book
-
Chapter 4. Exercise. countEven wants (future topic) pattern matching Ch4 - Is it possible to solve the countEven exercise without pattern matching? #303-
Solved by chapter 4-5 swap
-
-
Chapter 4. Cover ADTs (andMaybe) beforedonotation Ch4 Defer Array do notation section #212-
Partially handled by the swap and prev. issue
-
- Chapter 6. Improve explanation of Multi Parameter Type Classes and Functional Dependencies Improve explanation of Multi Parameter Type Classes and Functional Dependencies #238
- Chapter 6. ****Add content on deriving instances Add content on derriving instances in Ch6 #149
- Chapter 7. Discuss zippy Array and List Ch7 - Discuss zippy Array and List #236
- Chapter 7. Align definitions of
combineListandsequenceCh7 Align definitions ofcombineListandsequence#155 - Chapter 8. Clarify Monads and Applicatives Clarify Ch8 - Monads and Applicatives #186
- Chapter 8. Clarify
Either eCh8 - ClarifyEither e#162 - Chapter 11. Add example(s) of Reader Chapter 11 #412
- Chapter 13. Check QuickCheck ****with docs Ch13 - compare QuickCheck guide #188
- New. Add a spy (Chapter 4 or somewhere else) Cover Debug.Trace? #270
- New. Consider introducing typed holes (Chapter 6 or extra) Consider introducing holes and undefined #233
- New Chapter. Add content on Row Types and Variants Add content on Row Types and Variants #60
Reacted by Miles Frain- Chapter 3. Functions and Records
Some of the book's content is presented in a non-ideal sequence which frustrates beginners in the following ways:
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) beforedonotation (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.