Editorial Review - Get Started, Chapter 1

[simonstl]

Editorial review, not a searchable issue.

Edition: (1st or 2nd) 2nd

Book Title: Get Started

Chapter: 1

In a lot of ways, this chapter is a walk through all the human messiness surrounding JavaScript. Naming and standardization challenges, our preferences for varying approaches, change over time, discipline or the lack thereof... that might be worth announcing early, as this chapter feels very different from everything else that follows.

The "Many Faces" section is critical, and doesn't seem to me like it belongs between "Name" and "Specification". I would make "Specification" come right after "Name". "Many Faces" could follow, or it could be (with some modification) the opening section of the chapter. I think that "Many Faces" and "The Web Rules Everything About (JS)" are the key sections of this chapter that readers must absorb. (Putting "Many Faces" after "Specification" would make the chapter structure neatly foreshadow the conclusion of the chapter in "Defined".)

Intro:

The opening to the book doesn't work especially well as the opening to the chapter. I know that the preface is meant to be the same for the whole series. I think, though, that a section in each preface specific to the book might be a better option than starting the first chapter with this material. Granted, it's probably less of an issue in the books more focused on a small set of topics.

I would also emphasize that in many ways this book is a collection of highlights, emphasizing key topics that get deeply into how JavaScript works. If they are JavaScript tourists who will read only one book in the series, it really should be this one.

Name:

How many years has that Java / JavaScript naming overlap cost us ink and pixels and time? (Just venting, not an editorial comment.)

For stronger emphasis on the lack of relationship, I'd suggest changing:

But those are actually mostly from a common root: C (and to an extent, C++).

to:

Those similarities don't come from shared development, but from both languages inheriting syntax expectations from C (and to an extent, C++).

Also:

In fact, the relationships run even deeper than the superficial.

to:

In some ways, the legal relationships run deeper than the syntax.

You write "Some have suggested we use JS instead of JavaScript. That is a very common shorthand, if not a good candidate for an official language branding itself." I'd add that "These books use JS as the name of the language."

Many Faces:

I love this section generally - in a lot of ways, this is the heart of the JavaScript story.

Could you take this section:

"Examples of typical paradigm-level code distinctions: procedural, object-oriented (OO/classes), and functional (FP).

Broadly speaking, procedural code is focused on top-down, linear progression through a pre-determined set of operations, collected together in units called procedures. OO code typically orients logic and data into units called classes. FP code stresses functions (pure computations as opposed to procedures) and the adaptations of functions as values."

and rearrange it as a list, so people see the parts more easily?

Typical paradigm-level code categrories include: procedural, object-oriented (OO/classes), and functional (FP).

• Procedural code focuses on top-down, linear progression through a pre-determined set of operations, collected together in units called procedures.

• OO code typically orients logic and data into units called classes.

• FP code stresses functions, pure computations as opposed to procedures, and the adaptations of functions as values.

Now that I see it as bullets, I'd suggest taking another pass over those descriptions, whether or not you make it a list. These are descriptions that will be lurking in the background of all of these books, and having something concise you can point to may be helpful in future conversation.

It would also be a good candidate for a definition list, but I don't think Markdown supports those. (HTML dl/dt/dd.)

Specifications: This is the best description of the process I've seen. No changes!

The Web Rules Everything About (JS):

This section is great. The only thing I would add is that it's not just about semantic variations, but also about the long slow march of performance optimization. In general, the engines have improved enough that developers don't need to spend so much time choosing among JavaScript structures to avoid delays. However, there's still a lot of old material out there suggesting particular approaches because of things that used to be issues in V8 in particular. JavaScript still has performance issues, of course, especially on cheap phones, and that might be worth bringing up here or elsewhere.

Not All (Web) JS:

I usually support shorter paragraphs, but some of these might be combinable. If you want grammatical purity, "It depends on" would be cleaner than "Depends on", but I like "Depends on" as more conversational.

Backwards & Forwards:

This is great. The only thing I might change is that you could start with the pleasant dream of having a language that supports both forwards and backwards compatibilty, and then look at how it breaks down in practice. That might make it easier to tell a story that gets tangled. (For example, I routinely use the features of HTML & CSS that make them forwards-compatible to create sites that are still backwards-compatible to Lynx and IE 4.) That's an optional rearrangement.

Jumping the Gap and Filling the Gap:

I like these both. Maybe make Gap into Gaps? It's kind of one gap between versions, but it's made of lots of smaller gaps. That matters less when jumping than when polyfilling.

What's In an Interpretation?

This one is more complicated.

Something simple - drop "Let's consider the question in more detail. To start, why do people even debate or care about this? Why does it matter?" It isn't really necessary, and the flow works better without it.

More complicated: I would love to have a graphic showing the life cycle suggested by: "the entire flow of a JS source program: after it leaves a developer's editor". Compare it to a graphic showing the life cycle of a traditional compiled program. Numbered lists showing sequence might be an easier alternative. (Please indicate Babel and Webpack as optional?)

Also, "compiled to what?" for languages proud to be "compiled" is always a fun question. Compiled to bytecode, like Java? Compiled to machine language ready to go into a specific processor in a specific context? I enjoyed playing with Crystal last year, but any time I thought about distributing programs, even crossing operating system boundaries on the same laptop, the brittleness was obvious. JavaScript is SO MUCH MORE FLEXIBLE!

I think this section needs to mention WebAssembly, even if it's just an aside or note at the end.

Strictly speaking:

The content here is great, but I'd suggest adding one more piece. For developers who work in teams (most of them), consistency is even more important than usual. Strict mode (and linters) seemed most welcomed by those folks, and least loved by people who see themselves as bold and independent spirits.

Could you turn the "A minor gotcha" paragraph into a Warning callout?

Defined:

This is a great way to end. It echoes the chapter's structure (plus or minus the note above about where to put Many Faces), and summarizes things tightly.

[getify]

The opening to the book doesn't work especially well as the opening to the chapter.

What if chapter 1 of each book had a first section (immediately after the chapter intro) that was called "About This Book" and intro'd what to expect from the book, who its audience is, etc? That way it's there easy to find if people want it (even in the TOC), but it's also easy to skip over for those who don't care.

[getify]

The only thing I might change is that you could start with the pleasant dream of having a language that supports both forwards and backwards compatibilty

Are there any programming languages that are forwards-compatible? That would be wild/strange for a program to just skip over a whole statement because it used a syntax (like await) unfamiliar to the engine.

[simonstl]

Yes, an About This Book section could work, and would also let you write a more explicitly "welcome to the topic" first paragraph.

[simonstl]

On forwards- and backwards-compatibility, I don't know of any forwards-compatible languages, at least imperative languages. It's at least possible in declarative languages. Mostly I meant that it would make sense to talk about the perfect world in which programmers didn't have to worry about these things, and then DASH THEIR DREAMS I mean explain why they can't have that paradise.

[getify]

I also need to add a section talking about how REPLs and consoles are not real JS program environments, despite their resemblance.

[simonstl]

Yes - I would love a clear explanation of what REPLs and consoles are and do.

[getify]

NOTE: I still have a figure to produce for this chapter