Backticks confusing in examples

[benjamingr]

I've just had the second person using normal ticks instead of backticks and not understanding why examples aren't working. Template strings are a relatively new feature and people are getting confused by the examples:

I think our examples should somehow emphasize that these are backticks (not really sure how), or we should avoid backticks except when discussed in the examples, or we can have a small FAQ page for that.

As it is, users get confused. Opinions?

I can write a PR once a decision is made.

[Qard]

Sounds reasonable to me. Confusion is bad. 😢

[MylesBorins]

I have mixed feelings about this. The individuals who are most likely to be confused are going to be newer developers, and for them all the syntax is new and potentially confusing.

templating strings remove a slew of unnecessary code, and I do not believe the mental over heads is tremendous.

We could add a highlight / tooltip to all back ticks with extra information as one potential solution.

We could also potentially include a basic js syntax guide in the docs, including a bit about string interpolation, and include links to it.

[benjamingr]

The individuals who are most likely to be confused are going to be newer developers, and for them all the syntax is new and potentially confusing.

I bet most experienced JS developers currently do not know template strings (or generators, or classes). Most JS developers code to the browser and don't use transpilers or only support the very newest browsers. The fact most teaching material doesn't cover ES2015 features doesn't help.

It's also very common for documentations to have the incorrect type of quotes - so it seems reasonable they'll run examples thinking backticks are just ticks. Assuming the people reading the docs know the language is also something I'm not sure I agree with. I think a lot of these examples can be written almost as cleanly without template strings.

That said, I'm all for catering for experienced developers who spend time keeping up to date with the language and I think it's our obligation to help push the newer features forwards through the docs.

So really - I'm content with either removing the template strings or with documenting them explicitly somehow.

[chrisdickinson]

I'm +0 on template strings and other ES2015 additions that lend themselves to brevity in code examples: the longer the code sample, the easier it is to lose the context of the surrounding document. I agree with @benjamingr that we should figure out a place to link for users to get more background on the language.

This might be a sign that we need to start building out some docs on the docs. That is, we may want to add a section that says "This is how classes are documented, this is how methods are documented, this is the style code blocks are written in, and here is a place to look for reference on the language in the code blocks." This should be a document that answers "I don't understand what I'm reading, what is this?" and directs these folk to other resources (like MDN!) to get them to a place where our docs make sense. This might also include a glossary, which would be helpful in reducing the amount of jargon in the docs!

[kahwee]

How about using backtick examples sparingly and have it be always accompanied by the non-ES2015 version.

For example, this example code:

fs.readFileSync(__dirname + '/hi.txt')

Alternatively, with ES2015:

fs.readFileSync(`${__dirname}/hi.txt`)

This keeps the example simple while introducing some ES2015 concepts.

[rvagg]

I posted a possible way of dealing with this over @ nodejs/nodejs.org#467, for the about page of the website, but the same approach can be applied to all of our docs. Purely proof-of-concept at this stage, don't pick apart my frontend JS & CSS!

The markdown only needs to have Modern JavaScript: added before a code block, then ES5: followed by a code block with ES5. The work of putting it together is done in the browser, if for some reason that can't be done the fall back just displays the two blocks with titles above them so it gracefully degrades.

[stevemao]

I think nodejs website isn't a place to learn JavaScript. The language is evolving from time to time and inevitably new features will be added to nodejs and the docs. We already have a page for esNext and it lists all the feature that corresponding nodejs supports (this could be improved though). As long as the code snippets work under the corresponding nodejs I think it should be fine. If they are using an old nodejs then some api in the latest docs may not work for them, which is as bad.

[benjamingr]

+1 this is definitely a welcome fix, if we default to "Modern JavaScript" it's a good fix IMO.

As long as the code snippets work under the corresponding nodejs I think it should be fine.

See the above discussion, a lot of web developers starting with NodeJS don't have a backend background nor know ES2015 - having to deal with both at once doesn't seem very welcoming to me.

[benjamingr]

I've just shared the gif with both users who originally had the template string issues and received very positive feedback - in case that counts.

[chrisdickinson]

OK, the resolution on this from the meeting was:

• We will look into changing the font / highlighting template strings differently to call them out.
• We're going to look into ways to receive feedback from folks reading the docs, especially newcomers.
• We'll continue to experiment with this approach in the future, but:
  • There are concerns about doubling the number of examples we're tracking & increasing the maintenance load for the future.

Thanks all!