-
Notifications
You must be signed in to change notification settings - Fork 31
Backticks confusing in examples #55
Comments
Sounds reasonable to me. Confusion is bad. 😢 |
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. |
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. |
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! |
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. |
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 |
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. |
+1 this is definitely a welcome fix, if we default to "Modern JavaScript" it's a good fix IMO.
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. |
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. |
OK, the resolution on this from the meeting was:
Thanks all! |
I'm new to node and was working on a beginner's exercise that told me to use readline from here.https://nodejs.org/api/readline.html I didn't notice that it was a back tick, but I was put right by Sridhar in this post https://stackoverflow.com/questions/7790811/how-do-i-put-variables-inside-javascript-strings-node-js/32695337#32695337 It would be really handy for beginners if you mention on the readline page that it is a back tick. |
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.
The text was updated successfully, but these errors were encountered: