Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Get Started, 2nd pass editorial review #1565

Closed
simonstl opened this issue Dec 12, 2019 · 1 comment
Closed

Get Started, 2nd pass editorial review #1565

simonstl opened this issue Dec 12, 2019 · 1 comment
Labels

Comments

@simonstl
Copy link

@simonstl simonstl commented Dec 12, 2019

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.

Preface

Overall, this is great. I especially like "I don't think it's possible to ever fully know JS."

This sentence doesn't quite make sense to me: "These books approach JavaScript intentionally the opposite of The Good Parts." A word seems missing, but I'm not certain what.

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!

Chapter 1

Still refers to this book as "Getting Started".

Tiny nit - "Oracle (via Sun), the company that still owns and runs Java, also owns the official trademark for the name "JavaScript" (via Netscape)." I think Sun also owned the trademark on JavaScript. Netscape licensed the trademark, and it's assets went to AOL.

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!

Chapter 2

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" ?

Chapter 3

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.

Chapter 4

"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.

Appendix A

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.

Appendix B

I still love these!

@getify getify added the editorial label Dec 12, 2019
getify added a commit that referenced this issue Dec 12, 2019
@getify

This comment has been minimized.

Copy link
Owner

@getify getify commented Dec 12, 2019

I still want more figures

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 4-6 are great, but I don't see a 1-3.

Figures 1-3 are in Chapter 1, as you noted. I always number figures per book, not per chapter.

"bespoke" is a word I've learned to be cautious with

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'm not certain about this appendix, though.

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.

Putting them in an appendix makes them feel more optional than they probably are.

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!

@getify getify closed this Dec 12, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
2 participants
You can’t perform that action at this time.