Skip to content
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

Closed
wants to merge 1 commit into from
Closed

Conversation

Trott
Copy link
Member

@Trott Trott commented Sep 25, 2018

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), or vcbuild test (Windows) passes
  • documentation is changed or added
  • commit message follows commit guidelines

@nodejs-github-bot nodejs-github-bot added the doc Issues and PRs related to the documentations. label Sep 25, 2018
@Trott
Copy link
Member Author

Trott commented Sep 25, 2018

(Also, there is a link to the website right at the top, and the Foundation is linked from there.)

Copy link
Member

@jasnell jasnell left a 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.

@Trott
Copy link
Member Author

Trott commented Sep 25, 2018

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.

Copy link
Contributor

@refack refack left a 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.

@refack
Copy link
Contributor

refack commented Sep 25, 2018

@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.
It could be moved to the footer of the doc, though.

@addaleax
Copy link
Member

@jasnell Would you be okay with moving this down further the document, like @refack suggested?

@jasnell
Copy link
Member

jasnell commented Sep 30, 2018

I don't think a change is needed here at all but won't block moving it further down

@Trott
Copy link
Member Author

Trott commented Oct 6, 2018

I restored the sentence but moved it to the end of the paragraph rather than the beginning. I also reworded it so that it was active voice rather than passive voice.

@refack @jasnell LGTY?

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.
@Trott
Copy link
Member Author

Trott commented Oct 6, 2018

@Trott
Copy link
Member Author

Trott commented Oct 6, 2018

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.)

@Trott Trott dismissed jasnell’s stale review October 6, 2018 21:29

text restored, moved to end of paragraph

@Trott
Copy link
Member Author

Trott commented Oct 6, 2018

Landed in 1328dfa

@Trott Trott closed this Oct 6, 2018
Trott added a commit to Trott/io.js that referenced this pull request Oct 6, 2018
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 <[email protected]>
Reviewed-By: Anna Henningsen <[email protected]>
Reviewed-By: Ruben Bridgewater <[email protected]>
Reviewed-By: Michaël Zasso <[email protected]>
Reviewed-By: Colin Ihrig <[email protected]>
Reviewed-By: Refael Ackermann <[email protected]>
targos pushed a commit that referenced this pull request Oct 7, 2018
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 <[email protected]>
Reviewed-By: Anna Henningsen <[email protected]>
Reviewed-By: Ruben Bridgewater <[email protected]>
Reviewed-By: Michaël Zasso <[email protected]>
Reviewed-By: Colin Ihrig <[email protected]>
Reviewed-By: Refael Ackermann <[email protected]>
targos pushed a commit that referenced this pull request Oct 7, 2018
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 <[email protected]>
Reviewed-By: Anna Henningsen <[email protected]>
Reviewed-By: Ruben Bridgewater <[email protected]>
Reviewed-By: Michaël Zasso <[email protected]>
Reviewed-By: Colin Ihrig <[email protected]>
Reviewed-By: Refael Ackermann <[email protected]>
sagitsofan pushed a commit to sagitsofan/node that referenced this pull request Oct 12, 2018
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 <[email protected]>
Reviewed-By: Anna Henningsen <[email protected]>
Reviewed-By: Ruben Bridgewater <[email protected]>
Reviewed-By: Michaël Zasso <[email protected]>
Reviewed-By: Colin Ihrig <[email protected]>
Reviewed-By: Refael Ackermann <[email protected]>
jasnell pushed a commit that referenced this pull request Oct 17, 2018
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 <[email protected]>
Reviewed-By: Anna Henningsen <[email protected]>
Reviewed-By: Ruben Bridgewater <[email protected]>
Reviewed-By: Michaël Zasso <[email protected]>
Reviewed-By: Colin Ihrig <[email protected]>
Reviewed-By: Refael Ackermann <[email protected]>
@Trott Trott deleted the passive-01 branch January 13, 2022 22:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
doc Issues and PRs related to the documentations.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

9 participants