Skip to content

Improve ordering of content #340

Open
@milesfrain

Description

@milesfrain

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 and pure without discussing bind 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions