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

Documentation #1916

Closed
dannypike opened this issue Oct 13, 2019 · 2 comments
Closed

Documentation #1916

dannypike opened this issue Oct 13, 2019 · 2 comments

Comments

@dannypike
Copy link

Please remove unhelpful opinions from the README.md, such this:

* Easy to use, consistent interface

In my opinion, gyp is a very poorly-documented, arcane system that is anything but easy to use. It may have seemed like a good idea to deploy it at the time that the original decision was made, but I cannot agree that it is appropriate to claim that it is "easy to use", or that it "takes away the pain" of building anything.

A README should not express opinions, it should provide helpful information, such as a list of possible sources of help in deciphering the arcane language that is required to build a functioning binding.gyp for anything more complicated than "Hello, World".

@rvagg
Copy link
Member

rvagg commented Oct 13, 2019

Pull requests are welcome. Otherwise, your opinions about the opinions in the readme are just that.
We're trying very hard to improve the state of node-gyp after a long period of neglect, in our own volunteer time. You are not contributing to this effort and your issue is not helpful, but I hope your venting was cathartic.

@rvagg rvagg closed this as completed Oct 13, 2019
@dannypike
Copy link
Author

I'm sorry that you think the issue is not helpful. I was not trying to rant. I was reading the documentation and noticed something that I thought could be worded better.

So I decided to say that I think it is not a good idea to claim that something is "easy" when it may not be so for your readers. As for contributing to this project, I'm afraid that I can't help much, because I don't know enough about how node-gyp works. I've only just started using Node.js in a serious application. That is, after all, the reason why I was scouring the README.md for some help in the first place.

Nonetheless, I can give an alternative introduction here, as that doesn't require me to have any specialist knowledge. I hope it demonstrates my point. If not, I'll disappear back into my private cave and leave you alone. :)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants