-
Notifications
You must be signed in to change notification settings - Fork 29.8k
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
doc: shorten intro of README.md #23073
Conversation
(Also, there is a link to the website right at the top, and the Foundation is linked from there.) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Not really seeing this as a helpful change.
Every thing we jam into the README that the reader doesn't actually care about gets in the way of finding what they actually do care about. There's no need to have this one of the first things a reader sees. It is extremely unlikely this is the information a reader is looking for. There's probably no reason for it to be in the README at all. (It's on the website, which is fine.) Ultimately, I'd like to have a README that someone would actually read. Right now, we have a README that effectively tells the reader that there's a whole bunch of stuff in there they don't care about and they should skim it or perhaps not even bother with skimming. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
IMHO we need this.
@Trott I agree with the notion of "make it what the reader needs" (not what they care about). IMHO this is something they need to know. |
I don't think a change is needed here at all but won't block moving it further down |
There are many things I might want to know about if I'm reading the introduction of the README file for Node.js: Where to get help, what the latest release is, how to compile from source, where to report bugs, how to contribute... One thing I cannot imagine wondering about is, "I wonder if there is a foundation that supports Node.js." Move that sentence to the end of the paragraph as it is designed to serve the project and not the end user. Bonus: This removes a usage of passive voice. The Linux kernel README does not mention the Linux Foundation. https://github.com/torvalds/linux/blob/master/README The jQuery README does not mention the JS Foundation. https://github.com/jquery/jquery/blob/master/README.md (It does mention the no-longer-extant jQuery Foundation but only because the Foundation itself apparently had coding standards.) The Python README only mentions the Python Software Foundation as the copyright owner. The Apache httpd README does mention the Apache Software Foundation although it does not link to it and it is mentioned in passing rather than being the topic of a declarative sentence.
Given #23073 (comment), I think it's safe to remove the objection. (It's text and easy to revert if I'm doing the wrong thing.) |
text restored, moved to end of paragraph
Landed in 1328dfa |
There are many things I might want to know about if I'm reading the introduction of the README file for Node.js: Where to get help, what the latest release is, how to compile from source, where to report bugs, how to contribute... One thing I cannot imagine wondering about is, "I wonder if there is a foundation that supports Node.js." Move that sentence to the end of the paragraph as it is designed to serve the project and not the end user. Bonus: This removes a usage of passive voice. The Linux kernel README does not mention the Linux Foundation. https://github.com/torvalds/linux/blob/master/README The jQuery README does not mention the JS Foundation. https://github.com/jquery/jquery/blob/master/README.md (It does mention the no-longer-extant jQuery Foundation but only because the Foundation itself apparently had coding standards.) The Python README only mentions the Python Software Foundation as the copyright owner. The Apache httpd README does mention the Apache Software Foundation although it does not link to it and it is mentioned in passing rather than being the topic of a declarative sentence. PR-URL: nodejs#23073 Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com> Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de> Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Refael Ackermann <refack@gmail.com>
There are many things I might want to know about if I'm reading the introduction of the README file for Node.js: Where to get help, what the latest release is, how to compile from source, where to report bugs, how to contribute... One thing I cannot imagine wondering about is, "I wonder if there is a foundation that supports Node.js." Move that sentence to the end of the paragraph as it is designed to serve the project and not the end user. Bonus: This removes a usage of passive voice. The Linux kernel README does not mention the Linux Foundation. https://github.com/torvalds/linux/blob/master/README The jQuery README does not mention the JS Foundation. https://github.com/jquery/jquery/blob/master/README.md (It does mention the no-longer-extant jQuery Foundation but only because the Foundation itself apparently had coding standards.) The Python README only mentions the Python Software Foundation as the copyright owner. The Apache httpd README does mention the Apache Software Foundation although it does not link to it and it is mentioned in passing rather than being the topic of a declarative sentence. PR-URL: #23073 Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com> Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de> Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Refael Ackermann <refack@gmail.com>
There are many things I might want to know about if I'm reading the introduction of the README file for Node.js: Where to get help, what the latest release is, how to compile from source, where to report bugs, how to contribute... One thing I cannot imagine wondering about is, "I wonder if there is a foundation that supports Node.js." Move that sentence to the end of the paragraph as it is designed to serve the project and not the end user. Bonus: This removes a usage of passive voice. The Linux kernel README does not mention the Linux Foundation. https://github.com/torvalds/linux/blob/master/README The jQuery README does not mention the JS Foundation. https://github.com/jquery/jquery/blob/master/README.md (It does mention the no-longer-extant jQuery Foundation but only because the Foundation itself apparently had coding standards.) The Python README only mentions the Python Software Foundation as the copyright owner. The Apache httpd README does mention the Apache Software Foundation although it does not link to it and it is mentioned in passing rather than being the topic of a declarative sentence. PR-URL: #23073 Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com> Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de> Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Refael Ackermann <refack@gmail.com>
There are many things I might want to know about if I'm reading the introduction of the README file for Node.js: Where to get help, what the latest release is, how to compile from source, where to report bugs, how to contribute... One thing I cannot imagine wondering about is, "I wonder if there is a foundation that supports Node.js." Move that sentence to the end of the paragraph as it is designed to serve the project and not the end user. Bonus: This removes a usage of passive voice. The Linux kernel README does not mention the Linux Foundation. https://github.com/torvalds/linux/blob/master/README The jQuery README does not mention the JS Foundation. https://github.com/jquery/jquery/blob/master/README.md (It does mention the no-longer-extant jQuery Foundation but only because the Foundation itself apparently had coding standards.) The Python README only mentions the Python Software Foundation as the copyright owner. The Apache httpd README does mention the Apache Software Foundation although it does not link to it and it is mentioned in passing rather than being the topic of a declarative sentence. PR-URL: nodejs#23073 Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com> Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de> Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Refael Ackermann <refack@gmail.com>
There are many things I might want to know about if I'm reading the introduction of the README file for Node.js: Where to get help, what the latest release is, how to compile from source, where to report bugs, how to contribute... One thing I cannot imagine wondering about is, "I wonder if there is a foundation that supports Node.js." Move that sentence to the end of the paragraph as it is designed to serve the project and not the end user. Bonus: This removes a usage of passive voice. The Linux kernel README does not mention the Linux Foundation. https://github.com/torvalds/linux/blob/master/README The jQuery README does not mention the JS Foundation. https://github.com/jquery/jquery/blob/master/README.md (It does mention the no-longer-extant jQuery Foundation but only because the Foundation itself apparently had coding standards.) The Python README only mentions the Python Software Foundation as the copyright owner. The Apache httpd README does mention the Apache Software Foundation although it does not link to it and it is mentioned in passing rather than being the topic of a declarative sentence. PR-URL: #23073 Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com> Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de> Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Refael Ackermann <refack@gmail.com>
There are many things I might want to know about if I'm reading the
introduction of the README file for Node.js: Where to get help, what the
latest release is, how to compile from source, where to report bugs, how
to contribute...
One thing I cannot imagine wondering about is, "I wonder if there is a
foundation that supports Node.js." Remove that sentence as it seems
designed to serve the project and not the end user.
Bonus: This removes a usage of passive voice.
The Linux kernel README does not mention the Linux Foundation.
https://github.com/torvalds/linux/blob/master/README
The jQuery README does not mention the JS Foundation.
https://github.com/jquery/jquery/blob/master/README.md
(It does mention the no-longer-extant jQuery Foundation but only because
the Foundation itself apparently had coding standards.)
The Python README only mentions the Python Software Foundation as the
copyright owner.
The Apache httpd README does mention the Apache Software Foundation
although it does not link to it and it is mentioned in passing rather
than being the topic of a declarative sentence.
Checklist
make -j4 test
(UNIX), orvcbuild test
(Windows) passes