User:Duplode/AMP reorganisation plans

October 2016 plan

For the most part, Round 3 of the 2015 plans (see below) provides a good justification and a sensible road map towards completion of the AMP reorganisation. The main difficulty, however, is the status of the split Applicative chapter. Potential issues include:

Ideally we would want Applicative Functors I (now in the monads unit) to be neither too deep (to avoid overloading readers at a crucial juncture) nor too shallow (to avoid it being useless). The golden mean, however, is hard to get right. In particular, presenting the class and laws with only the clichéd "summing Maybes" example would feel too cursory, but exploring at some depth an interesting example would unbalance the book quite a bit. There is always the nuclear option of eviscerating everything, rearrange the fourth and five units into Allen & Moronuki's canonical MFAM and bring Traversable, parsers and the kitchen sink into play -- that, however, is rather pointless IMHO: for one, if we want the Allen & Moronuki order there is Allen & Moronuki available already (and, as argued in the 2015 Round 2 comments, I believe the monads-first order of the Wikibook is an alternative worth pursuing).

Related to the first point is the fact that after the first three units there are not many examples that can be mobilised quickly given the context of the earlier parts of the book. In fact, it is the job of the fourth and fifth units to bring in such examples -- but not en passant!

Stripping the first half of the current Applicative chapter to make Applicative Functors II would make it somewhat disjointed, no matter how much we try to mitigate things with careful in-book linking. Given how there are quite a few links to the current chapter around the Internet, that would be somewhat unfortunate.

What is to be done, then? What I'm about to propose is the Wikibook equivalent of an Aikido move. Given what happens in the first three units, which examples of Applicative that have some substantial context already developed we have available? First, there is List, which I don't see as a compelling introductory example. Then there is Maybe, which, as mentioned above, is a bit of a cliché at this point. Only one option remains... IO! One of the main underlying motivations of an early jump into monads is grasping what is behind bread-and-butter IO, yet we have to do it in an almost apologetic way in order to avoid the age-old mistake of associating IO and monads too closely. However, we can entirely subvert the issue by:

Creating a prologue to the fourth unit (WIP draft) with a title akin to "IO, the applicative functor".

In it, introduce Applicative using Maybe and a tiny motivating example in the spirit of those in "Simple input and output", but using readMaybe to read two integers and sum them. The introduction would be cursory: we would show the pure and return definitions, but not e.g. the laws, redirecting the curious reader to the full-fledged (and undivided!) "Applicative functors" chapter.

With that done, use rewrites of the same example to illustrate that IO is both Functor and Applicative. Part of the discussion about referential transparency currently in the IO subchapter would happen here, as well as some preliminary initial comments about sequencing of effects, under the guise of introducing *>.

Trim the "Understanding monads" chapters and the early parts of "Applicative functors" a bit to avoid too much repetition (some repetition is okay -- for someone reading the book from cover to cover the early sections would work well to provide recapitulation and exercises, much in the same way the current "Functor recap" section that opens the chapter now works at the moment).

Other than that, follow the 2015 Round 3 plan, except that dividing "Applicative functors" isn't necessary anymore.

2015 plans (with Backfromquadrangle)

These were copied from various talk pages.

Round 1

Suggestion: 1. I think Monoids should be moved to Intermediate section. 2. Applicative Functors needs a rewrite so that it is up to the standards of the rest of the beginner's track, but that should be done with the plan of building directly on the stuff only through the intermediate section, and we should then put Applicative Functors into the Monads section as the first chapter there before introducing Monads themselves. We can reference then that Monads are Applicative Functors and that this will be recognized in GHC 7.10. Backfromquadrangle (discuss • contribs) 15:33, 14 May 2014 (UTC)

I was thinking about the pros and cons of both reorderings yesterday. It would make a lot of sense to move Monoids to Intermediate (it would be a second early example of a type class, and would make it easier to discuss things such as MonadPlus). My only worry is whether moving it mould force us to dilute the examples too much; perhaps not. We certainly would not be able to mention Foldable, Traversable or Writer, though that won't be much of a problem once they get their own chapters.

As for Applicative, the situation looks much trickier to me. It is clear that presenting Functor, Applicative and Monad in decreasing order of generality would make some discussions less awkward (doubly more so once GHC 7.10 implements the AMP), and that it would not be difficult to introduce Applicative by presenting <*> as a generalisation of fmap to multiple arguments, as done by LYAH. However, building clear intuitions about Applicative seems harder than doing the same for Monad (that might be just personal bias though, YMMV!); that being the case, the discussion of applicatives might benefit from the experience gained in dealing extensively with monads. Furthermore, I think it might be desirable not to delay the full discussion of monads too much, given that in one way or another they are there almost from the beginning. In Cartesian terms, I think that when presenting results sometimes it might be a good thing to stick to the order of discovery, rather than following strict geometric order. I am not certain of any of that, though; it will probably be easier to tell once I carry out the rewrite of the Applicative chapter.

Duplode (discuss • contribs) 17:16, 14 May 2014 (UTC)

Good thinking overall. So it sounds like we agree about moving Monoids, and I like your thoughts about how to do it. For the Monoid topics not introduced by the intermediate stage, a mix of "we'll learn more about these items later" and actually have a later "advanced monoids" or "more Monoids" or something seems good.

My view, on Applicative: I totally got the Monad concept without Applicative as an intro. In fact, in many cases, showing more specific first and then broadening to more general is great, and much of the best parts of the book so far are in that order (specific first, general later). Both orders can work, depending on the approach. So, I'm not sure that Applicative should be first!

As is, Monads are explained so much better than Applicative that it appears to me that Monads are pretty easy and Applicative is baffling. I'm sure that's largely because of the difference in the quality of the chapters. So indeed, I agree with you, everything about Applicative depends on what we can achieve in better writing that chapter. Applicative could be used as intro to Monads or it could still come later as it does now. I don't think there's a single right answer. For example, I love how do is introduced early on even though the mathematics of it aren't introduced until Monads.

Whatever we do, I like the step-by-step reasoned examples approach that much of the beginning track has. That is more important than forcing a particular logical ordering in a meta sense. But maybe they can be compatible. Maybe we can both achieve that nice pedagogy and introduce Applicative before Monads. But if not, I definitely think the clear teaching is more important than the conceptual order. So I just think it'll be good to consider these options when rewriting Applicative. Backfromquadrangle (discuss • contribs) 19:01, 14 May 2014 (UTC)

Round 2

Hello again! How are you?

After a long while I have finally managed to return to the book - and it was good to see you around on the watchlist as well! The moment is proper: I sense a nice opportunity in that the Wikibook format allows us to react quickly to big changes such as the Applicative-Monad proposal. With that in mind, I started by doing the rewrite of Haskell/Applicative functors I promised a year ago; and so I invite you to have a look at it. Beyond improvements to the text, it also includes a reasonable number of exercises with solutions, and is GHC 7.10 compliant. It is also quite long, possibly the longest of all chapters up to that point of the book. Interestingly, however, it divides neatly into two parts of nearly the same size at the end of the ZipList section. Up to it there is introductory material, roughly correspondent to the old chapter; after it there are complementary topics at a slightly higher level of difficulty (the exercises get harder as well), including a section meant to unify the discussions about Functor, Applicative and Monad. I can easily see the chapter being divided into "Applicative functors" and "Applicative functors II".

That brings me back to the book sequencing issues we were considering a year ago. I still lean towards not moving Applicative before Monad -- the "wrong" order we currently use is a bit messier but also more accessible; furthermore, if everything else moves to the "right" order we would end up with a possibly useful differential from the other books -- though my opinion about that is not set in stone. Writing the Applicative chapter, however, gave me a crazy idea: what if we moved applicative (or at least the first half of its chapter) to the monads module? The distance between the related discussions would be lowered, and mixing Alternative into the MonadPlus chapter would become painless. I have no clue if that could be made to work, but it sounds like an interesting third option to think about. As of now, the applicative chapter for the most part assumes familiarity with monads, though it would be possible to tone it down in the first half of the text with rather few losses.

Over the next few weeks at least I shall keep working on the book. My next targets include cleaning up the State chapter and writing on Foldable and Traversable (which reminds me of the question about what to do with Monoids...) I would love to hear your thoughts on those issues!

Cheers, Duplode (discuss • contribs) 11:34, 4 July 2015 (UTC)

I'm still a beginner in many respects and have been editing mostly to reduce extraneous wordings while reviewing the basics. I look forward to getting to your updates about applicatives. I agree that the "wrong" order is okay when done for useful reasons. I think moving the first part of Applicative into the Monad chapter makes sense, thus splitting it into some sort of intro to Applicative vs later stuff. I'll try to keep pushing through and getting there. Incidentally, I liked some of the approach I saw in this series: http://andrew.gibiansky.com/blog/haskell/haskell-syntax/ (I also asked the author about licensing it freely, but we could consider some of those ideas just for reference anyway). I think I'd like to see a first-principles intro to Haskell that starts at the *very* core of the absolute minimal base of the language with no syntactic sugar and builds out from there, but I don't suggest that for the Wikibook as I like the Wikibook's approach already — it's just something complementary I'd also like to see. --Backfromquadrangle (discuss • contribs) 12:59, 4 July 2015 (UTC)

The series you linked to looks good indeed. For an extra data point, it is interesting to note the author goes directly from Functor to Monad, but covers Monoid before either of them. As for the first-principles intro idea, it sounds sensible. It reminds me of, back when I first started contributing here, how Apfelmus wanted to reorganize the early parts of the beginner track so that each thing was done with just one syntax variant (not necessarily the simplest). While the book is not exactly like that, it does tend introduce syntactic sugar slowly and in modest doses. By the way, your comment and link has reminded me of a very different sort of crash course: How to read Haskell like Python, a rather fun blog post by Edward Z. Yang. --Duplode (discuss • contribs) 04:21, 5 July 2015 (UTC)

Round 3

It has been two months since I last wrote to you about that topic, and I have changed my mind again. It is becoming increasingly clear to me that we can't avoid some discussion of applicative functors before monads. The AMP looms large, of course, but there are several other aggravating factors:

In a few months from now, GHC will offer the ApplicativeDo extension, which will be one more thing that might confuse newcomers.

Further into the future, but far more dramatically, there are the plans to move return out of the Monad class. That will likely take a few years to happen, but when it does it will become very hard to justify the current order.

Talking about MonadPlus before Applicative means there is no good place to discuss Alternative. That has ripple effects on several chapters. The most alarming is probably that, as type of guard was changed to use Alternative, there are wrong type signatures in the "MonadPlus" and "Monad Transformers" chapters. Another example is that not covering Alternative is blocking the inclusion of a section about ArrowPlus in "Understanding Arrows", which in turn makes the discussion of the big example in the second half of that chapter incomplete.

Having to pretend that (<*>) and liftA2 do not exist throughout the "State Monad" chapter is very annoying. A similar issue is that it would be replace mapM with traverse in the "IO Monad" chapter.

The notes about Applicative I tacked onto the end of "Understanding Monads" are quite unsightly.

A somewhat related issue is that currently the book only discusses functions as functors from the "Applicative Functors" chapter onward. That makes finding a place to introduce Reader awkward.

All of that is leading me to think of a way to introduce applicatives before monads without disturbing the chapter sequencing in the fourth and fifth units too much. What do you think about the following plan?

Move the recap exercises in "Applicative Functors" to their rightful place, the "Functor" chapter.

Add a casual (and very brief) note to the "Functor" chapter mentioning Foldable and how it generalises foldr. That would make it possible to show signatures that use it (e.g. for_) without worries. (Something similar would be done when introducing traverse in the "IO Monad" chapter.)

Split "Applicative Functors" and make the first part the first chapter of the "Monads" unit (the second part would stay where it is now). The parts to be moved are, roughly, the ones that already existed in some form before the rewrite, minus all references to monads; that is, "Application in functors" (the applicative style demo), "The Applicative class" (including the laws), and "ZipList" (which also shows the standard list instance). A few extra remarks on how Applicative combines contexts might be desirable, but we probably won't want to go too far into that.

"Applicative Functors I" would explain the bare minimum needed to go into monads without turbulence. That would make it possible to sprinkle examples of Applicative throughout the chapters about monads, and, later on, to resume the discussion of applicatives at a more sophisticated level in "Applicative Functors II". By the way, it is interesting to compare this sequencing with that of Allen & Moronuki, which does MFAM (Monoid-Functor-Applicative-Monad). That is a very sound order, but I see two reasons for not following it exactly here. Firstly, given the relative terseness of Wikibook chapters, a full treatment of the four typeclasses coming out of the blue during the transition between the third and fourth units might end up disorienting readers. Secondly, there is some interesting interplay between chapters in our MAFTAL (Monoid-Applicative-Foldable-Traversable-Arrow-Lens) sequence, and moving "Monoid" to the third unit would likely compromise some of it.

Once ApplicativeDo lands in GHC, add a brief note about it in the "do Notation" chapter.

Use traverse, (<*>), etc. where appropriate in the monad chapters.

Rewrite the "MonadPlus" chapter as "Alternative and MonadPlus", and fix the related problems in other parts of the book.

Cheers, Duplode (discuss • contribs) 04:51, 28 September 2015 (UTC)

I have no objections or disagreements here at all. I haven't made it through the advanced stuff myself yet anyway. It seems you've thought things through well. I like the two-stage Applicative idea. Backfromquadrangle (discuss • contribs) 06:03, 3 October 2015 (UTC)