User:Duplode/Haskell preface

Pedagogy

• Spiral approach: Concentrating all discussion of a topic into a monolithic chapter frequently isn't the most effective way to tackle it. Rather, introducing a subject at a more elementary level and returning to it later on in increasingly sophisticated levels can be more flexible for the writers and easier to take for the readers. Spreading discussion of an issue also creates opportunities to establish links between topics. Preliminary discussions might be anything in scale − from a casual mention in a footnote to a whole chapter.

• Flawed metaphors are evil: Broaching a subject with vague, incomplete, imprecise or simply wrong metaphors can be confusing. Even worse, it may lead readers into building poor intuition. It is necessary to be careful with analogies and approximations, and to be frank and forthright in recognising their eventual weaknesses. See Brent Yorgey's classic remarks on the theme, "Abstraction, intuition, and the "monad tutorial fallacy".

• Assume as little as possible: The book should be useful to readers with no previous programming experience. Therefore, do not assume readers have experience with imperative code, OOP or that what a type is is obvious to them. For similar reasons, avoid having sections in the book that rely heavily on topics that weren't discussed yet, or were covered only superficially.

• Do not worry too much about scaring readers: If there is an opportunity to mention something interesting and relevant to the topic at hand, yet tangential and pertinent to something that will be introduce it later on, do not pass it just because it comes out of order. Brief tangents may be useful to prepare the ground for later discussions, and help keeping curious readers interested. Digressiveness and difficulty can be controlled by choosing carefully the length and the language of the extra comments.

• Do not drown readers in syntax and trivia: Specially early in the book, lengthy enumerations of library functions or syntax variants lead only to confusion and boredom. Keep the conceptual heart of the topics upfront.

• Geometric order is not always the best choice: Logical dependencies between topics need not determine the sequence of the book. Practical considerations, the perspective of the readers and approachability are just as important, if not more so. Also, too strict a linear sequence can make it unnecessarily hard for readers to approach a single chapter out of context.

• Text books also have story arcs: Chapters may be connected to each other in various forms. Sometimes there will be a direct linear development with a clear culmination point. Other times there will be a long series of chapters through which one or more themes are developed in a spiral. Another possibility is having a cluster of closely yet not linearly related chapters. Within a chapter, circular progressions can also be an interesting technique. In any case, narratives help making a book engaging.