search

npm / support-cli

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

What should go in here? #9

Closed faiq closed 9 years ago

faiq commented 9 years ago

Okay this issue is created in reaction to the comments in #3 and #7. We really need to figure out what the heck we should put in here:

  1. To make sure that the repo is cluttered with a ton of information that we have to maintain and update
  2. So users aren't overwhelmed with all the reading they think that they might have to do
  3. We should have relevant information regarding what this repo is, what belongs here, what a good issue looks like.

So I'm in favor of keeping this repository as short and sweet as possible. We should only have a small number of files (im thinking 2 or 3).

  1. Readme -> stating the purpose of this repository
  2. Contributing -> some information about what a good issue is, turn around time, (see #3 for more details with a link to Troubleshooting)
  3. I CANT THINK OF ANYTHING ELSE, CAN YOU?
smikes commented 9 years ago

TL;DR I totally agree

The long version

I had been thinking of this as "the new URL we send people to when they need support".

But once npm report lands, and assuming the endpoint is npmjs.org hosted (#9) then the user's experience will be:

$ npm foo bar baz
npm ERR! npm failed ...
npm ERR! To try automated fixes, run `npm doctor`
npm ERR! or report this issue with `npm report`
$ npm report
Gathering information.....
Submitting issue.....
Success!  View your submitted issue at https://github.com/npm/support-cli/issues/nnn
$

Then we can decide what text goes into the auto-generated issue, and direct the user to troubleshooting guides or whatever else -- but the main point is, nobody is ever coming and reading the README for this repository. Or rather, they are, but only after they've submitted an issue. Or they're reading it because they want to help with support. (Hey, it could happen...)

othiym23 commented 9 years ago

My only suggestion is that I prefer to think of npm doctor as a diagnostic aid, rather than some kind of magical self-service npm fixer. There will be a subset of users who will be able to use it effectively, but by and large, npm report should dump the results of an npm doctor run into the issue report, and that should be our go-to method for getting help.

Aside from that, yes, keep the docs here short and sweet, and primarily links to complete docs elsewhere. The actual repository is just a byproduct of needing a place to park our issue tracker that's not npm/npm.

smikes commented 9 years ago

Agree, agree. npm doctor is diagnostic. npm report is for asking for help.

Duplicated docs have been removed from the PR, which I will land.