search

npm / support-cli

File your support requests for the npm CLI here!
5 stars 6 forks source link

add some more to CONTRIBUTING.md #3

Closed smikes closed 9 years ago

smikes commented 9 years ago

Questions for others involved in cli support -

comments/thoughts ? /cc @faiq @iarna @othiym23 @KenanY

kenany commented 9 years ago

AFAIK there's just the #npm channel. I think its all we need; most of what goes on in it is support anyways I think.

CONTRIBUTING.md looks good so far. I'm kind of glad that the issue-submitting guidelines aren't as numerous as those that npm/npm's CONTRIBUTING.md points to. No one reads them from my experience on the issue tracker :(

smikes commented 9 years ago

no-one reads CONTRIBUTING.md

That's a problem with multiple causes... a big one is https://github.com/isaacs/github/issues/248

But also, it's that people are blindly going to the URL in the error message in front of them and clicking on something. Having npm report working will help with that.

faiq commented 9 years ago

I do like how it is going so far, but if this is going to be the the main page for support from now on, maybe we should be a little more through. Do you guys think that there's anything missing?

othiym23 commented 9 years ago

@faiq This should be as short and sweet as possible. Other resources (the npm wiki, docs.npmjs.com) have more other documentation. We just want to pry issues and environment details out of people having problems with as little friction as possible.

I think this file would actually work best as the README.md, actually, but we also do want people to be linked to this information from the issue tracker, which is what will happen automatically if it's lined as CONTRIBUTING.md. But to get people's eyeballs to avoid glazing over it definitely needs to stay concise.

faiq commented 9 years ago

I definitely understand the motivation to keep it short and sweet. Maybe links to some of those pages would be useful to someone?

smikes commented 9 years ago

Per @timoxley 's suggestion in #7 I have added the contents of the Troubleshooting page to the README.md and added a link from CONTRIBUTING to README

faiq commented 9 years ago

I agree with including the Troubleshooting page, however we need to keep a few things in mind

  1. We need to worry about how much text content we have in this repository, if its too much people would get intimated and wont read it.
  2. Figure out what the relative content is that we want to present.
  3. Where that information should live

It's just my opinion that the Troubleshooting stuff should be in its own file, and the readme file should explain the purpose of this repository.

othiym23 commented 9 years ago

The more places we have information, the more places we have to update and / or keep up to date. I'm totally in favor of linking to the Troubleshooting page, but not so enthusiastic about including the content in multiple places.

smikes commented 9 years ago

'The question is,' said Humpty Dumpty, 'which is to be master — that's all.'

I like that a README.md (or TROUBLESHOOTING.md, whatever) can have pull requests filed against it. Editing a wiki page is too easy and doesn't leave a history..

othiym23 commented 9 years ago

Editing a wiki page is too easy and doesn't leave a history..

It doesn't? https://github.com/npm/npm/wiki/Troubleshooting/_history

I really don't want to have too much documentation on this repo. It's not the primary home of npm, and it's not the blessed home for npm docs. I would greatly prefer only summaries and links.

smikes commented 9 years ago

Thanks, I don't know how I overlooked that. I guess I was thinking of a full public history like with pull requests, and the opportunity to review before changes go live.

For example the Troubleshooting guide links to https://gist.github.com/isaacs/579814 which (although awesome) is

  1. 4 years old
  2. not indicative of the way most people are installing node/npm now (via a joyent installer or through their OS distribution)

I wanted to edit it to have more up-to-date information, for example bringing in the information here: http://blog.izs.me/post/87525128203/how-to-install-node-js-and-npm-on-ubuntu-14-04

sudo apt-get install python-software-properties
sudo add-apt-repository ppa:chris-lea/node.js
sudo apt-get update
sudo apt-get install nodejs
sudo npm install npm -g

But then it turns out that even that is obsolete (but only recently so) because ppa:chris-lea is deprecated, which led me to https://github.com/nodesource/distributions as the best guide to install node on Debian/Ubuntu.

othiym23 commented 9 years ago

Lard knows GitHub wikis are obtuse and "minimal" (i.e. not very useful), but my main point is that the best home for that information is not here.

@zeke argues (pretty persuasively) that it belongs on docs.npmjs.com (where it will have better SEO), but my counterargument has been that it's very handy to be able to go tack stuff onto it without any hassle when I realize that something has come up enough to need to be in the document. When I'm in the throes of reviewing looks 104 npm notifications, flexibility and ease are my primary concerns. Which is a fancy way of saying that eventually I'll hand all that information over to @linclark and she'll take it and do useful things with it and it'll end up on docs.npmjs.com anyway. And also that npm, Inc. views CMSes with fear and distrust, as is natural and proper.

smikes commented 9 years ago

best home.. is not here

Agreed. Removed "TROUBLESHOOTING.md" as contents of README. Added something more README-ish

Regarding CMS & documentation, fear and distrust is only natural.

Also : http://www.slideshare.net/evangoer/yuiconf-2013documentationiscode

What about adding the nodesource link to the wiki? yes/no/politics?

othiym23 commented 9 years ago

What about adding the nodesource link to the wiki? yes/no/politics?

Do it! If you can't (I can never remember how GH wiki perms work), let me know and I will.

smikes commented 9 years ago

I edited the wiki. Review requested, comments/edits welcome.

I think I'm going to land this PR so we can find a new place to bikeshed.

smikes commented 9 years ago

104 npm notifications

btw @othiym23 is there someone else I should/could be bugging other than you? I would like to be able to help without adding to your workload -- which may be impossible, but I thought I'd ask.

Eg if I have suggested tags for new issues that come into npm/npm/issues, can I bug @faiq with those?

faiq commented 9 years ago

sorry @smikes I don't work at npm anymore so you can if you want, but I am not allowed to close issues or set new flags. Sorry, but I can totally help you in any other way, aka help out with issues/ talk through some problems with you!

othiym23 commented 9 years ago

@smikes if you have questions / requests about support stuff, @iarna and me are the ones to bug, because we're the ones ultimately responsible for keeping things headed the right direction. I don't think there's any way to make this zero-cost for me, but I think the force multiplier of getting more people involved more than compensates.