getify
commented
7 years ago I believe I've addressed the feedback from this thread. Ultimately, I decided not to combine chapters 2 and 3, though I have spent several months contemplating that approach. However, I do believe the organization of content between the two chapters, and indeed the actual purposes for them as separate chapters, was NOT clear before.
I've thus moved several sections around, rewritten transitions, renamed sections, even renamed a whole chapter, in an effort to clarify why these 2 chapters are the way they are.
For posterity sake, here's the summary:
-
Chapter 2 is all about how functions themselves work, including the nature of parameters, return outputs, closure, this, etc.
-
Chapter 3 is all about techniques we can use to manipulate functions to bend them to the shapes and behaviors that we need. All the techniques in this chapter are about adapting functions.
I believe those are both important, and distinct, messages, and deserve their own chapters. To the extent that those lines were too blurry before, and it seemed like these chapters needed to be combined, I think I've ultimately decided that the book is stronger if I keep them separate and strengthen the why of that separation. Hopefully I've done that. :)
Based on the conversation we had earlier this week, and reading this now, it's clear that Chapter 2 and 3 are intertwined. I think combining them would probably be a good choice, and there are clear signposts in the current 3 where chunks from 2 could go -- I've highlighted these in my comments. The trick will be doing this without blowing up the merged chapter to gargantuan proportions. My suggestion for that would be to keep the asides and edge cases to a minimum in the transferred pieces.
The intro could be beefed up some. The promise here is "I'll show you several techniques for creating functions with a single parameter," that much is clear. A reminder of why that's good, or some use-cases where that could come in handy, would engage the reader more.
"Some Now, Some Later" section "Notice the references to fn and presetArgs inside this inner function? How does that work?" -- if you're thinking about merging Chapters 2 and 3, this would be a place where you could move the closure discussion.
"See how important understanding closure is?" A small point, but a declarative sentence: "This is why understanding closure is critical," or similar, reads better. Rhetorical questions can become frustrating to the reader, because the question assumes the reader's response.
"One at a Time" section "This technique is called currying." -- I'd add an intensifier on this, something like, "You're going to see this a lot."
"We're going to use some tricks from Chapter 2." As we discussed, bringing in the Chapter 2 techniques at this point may be more useful than introducing them in advance and asking the reader to remember them (or go back and re-read).
"Why Currying And Partial Application?" -- when I'm asking a question in my head, and that question is the very next heading, that's a good sign.
"One On One" section This discussion of how
identity(..)can be used when splitting a string -- does that meet the readability standard? It works, but it doesn't seem immediately obvious to the reader why it works."Spread 'Em Out" section "In Chapter 2, we briefly looked at parameter array destructuring." Once again, if you wanted to talk about destructuring here instead of Chapter 2, that would be a valid choice.
"Order Matters" section Not to make this a theme, but you could discuss the named arguments from Chapter 2 here.
I like the "don't go overboard with this stuff" warnings in appropriate places in this chapter.
"No Points" section I think there's a "why" missing from this section. I get that point-free style is considered a good thing within traditional FP, but why is it a particularly good idea in JS, or for this book's audience? What do you gain from it? This is especially important if you're asking readers to make a value judgment on whether it's useful for them, because while your final example is fairly readable, it does rely on several other utilities which the reader has to understand first.
Summary -- You're summarizing the topics, which is important. You should also remind readers that you've fulfilled the promise of showing them how to create single-parameter functions, and why that's a good thing. Specifically, give me the connection to composition, which comes in the next chapter.