Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.Sign up
Get Started, 2nd pass editorial review #1565
Editorial review, not a searchable issue.
Edition: (1st or 2nd) 2nd
Book Title: Get Started
Get Started, Pass 2
In general, this feels much smoother to me, with topics reinforcing each other smoothly.
I still want more figures, but you've noted that in the earlier issue closings, so I'm not repeating that here.
Overall, this is great. I especially like "I don't think it's possible to ever fully know JS."
The section on The Path, and the warning about "Nobody can really hope to download all this information to their brains in a single pass and retain any significant amount of it" is perfect. Doubtless someone will take that as a challenge, though!
Still refers to this book as "Getting Started".
This is getting into copyediting, but maybe "They are primarily tasked" -> "Their primary task is"
"Using the console/REPL (Read-Evaluate-Print-Loop) in your browser's Developer Tools" - I'm not sure you want to limit that to the browser? You've spoken more broadly, including Node, elsewhere.
The figures definitely help tell the story!
The opening feels much better.
I was going to complain that objects are still kind of buried in "Arrays and Objects", but it's actually appropriate. Maybe explicitly mention that one of the kinds of things that objects can contain is functions?
"The variations are minor, though. All of these forms rely on the same basic principles."
Add "incompatible" after "minor, though" ?
The 3rd and 4th paragraphs of the intro seem to echo each other. Maybe that's for emphasis, but maybe combine?
Iteration, first sentence, have instead of has. Happy to see iteration first in the chapter!
Figures 4-6 are great, but I don't see a 1-3.
"bespoke" is a word I've learned to be cautious with. It's not just that many people don't know what it means, but it's also a word people seem to add their own meanings to. It's okay to use it, but I'd probably not use it standing on its own.
The title claims that this is Appendix B.
I liked the flow of the book much better this time around, so I think rearranging things has helped. I'm not certain about this appendix, though. While everything in it is valuable, it seems trapped between the broad view of this book and the details that the rest of the series will provide. Putting them in an appendix makes them feel more optional than they probably are. It's probably fine.
I still love these!
I added 6 figures to the book per your feedback! I am not much of a graphic artist, so it's not my inclination to illustrate everything in figures. I prefer to "illustrate" with code, which is my books are always very code heavy.
Figures 1-3 are in Chapter 1, as you noted. I always number figures per book, not per chapter.
I used it here because TC39 members literally use it on this exact topic. I agree though, it's not a well understood word. I changed it to the phrase "directly and explicitly".
I didn't want to just delete this content. If you recall, we discussed earlier that my plan with these books would be, in places, to move some of the deeper explorations of details (the real "in the weeds" stuff), and/or chunks of my heavy-handed opinion sharing, out of main content into an appendix. That's because some feedback from 1st edition was people felt that, at times, the text was too weighted down by such stuff.
So I realized, when going through your edits, that this was exactly what was happening with these specific topics... they were weighing down the text in those places too much.
But the reason they're in an appendix and not just deleted is, this book is not an "intro" book, it's an intermediate book that is supposed to prepare readers for the depth of the subsequent books, namely Scope & Closures. In 1st edition, many felt there was too big a gap between "Up & Going" and "Scope & Closures", so this book was shifted from a very-simple-beginner-intro up to an "intermediate-preparatory-preview".
The other books will all have (at least) an Appendix A like this, where I move the "really in the weeds" stuff to. It makes sense to reflect that predictable structure in all six books.
Optional is a decent word. "Defer'able for now" is probably the best intent.
In my mind, I sorta see readers skipping this appendix at first read-through, and then re-reading the book (or parts of it), working on the appendix B practice exercises, etc. But then coming back and reading this appendix at the very end before moving on with the rest of the books. That's why it's an appendix and not main body text.
Thanks for all your great editorial feedback!