Comments (11)
Sounds reasonable to me. Confusion is bad. 😢
from docs.
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.
from docs.
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.
from docs.
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!
from 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.
from docs.
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.
from docs.
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.
from docs.
+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.
from docs.
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.
from docs.
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!
from docs.
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.
from docs.
Related Issues (20)
- Node v6.3.1 docs: net.Socket HOT 1
- StackOverflow Documentation for Node.js HOT 5
- Circular reference for OS Constants HOT 3
- http ClientRequest documentation unclear about inheritance when visually scanning HOT 2
- .read() stream not fully explained HOT 9
- Rough Meeting Notes (2016-12-01 @ NINA) HOT 8
- What errors can be thrown?
- Async meetings HOT 6
- How-to use LetsEncrypt Guide HOT 13
- Meeting #1 HOT 33
- Add @vsemozhetbyt? HOT 4
- Meeting #2 HOT 2
- descriptions of "The module Object"'s property are not clear HOT 1
- clarity on asynchronous methods throwing exceptions HOT 2
- http.ClientRequest is missing some methods HOT 3
- Package documentation (how to intl) HOT 1
- Decharter this Working Group? HOT 8
- Better wording for modules_all_together HOT 3
- Suggestion: Return type in function declaration & possible option to view types by clicking HOT 2
- Improve the words usage in socket.setTimeout() definition HOT 1
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from docs.