Improve upon installation instructions #333
Conversation
Improve instructions as per the issue:
- #332
specify codeblock language style
|
|
||
| - #### NPM | ||
| ``` | ||
| npm install js-cookie --save |
There was a problem hiding this comment.
I'm not sure if using npm specific command example will help. People might be using yarn.
There was a problem hiding this comment.
extremely fair point. perhaps it's own header separated section as well?
There was a problem hiding this comment.
You mean creating one example for Yarn too?
| @@ -41,10 +41,28 @@ in Internet Explorer on Windows 7 for instance (because of the wrong MIME type). | |||
|
|
|||
| JavaScript Cookie supports [npm](https://www.npmjs.com/package/js-cookie) and [Bower](http://bower.io/search/?q=js-cookie) under the name `js-cookie`. | |||
|
|
|||
| - #### Bower | |||
| ``` | |||
| bower install js-cookie --save | |||
There was a problem hiding this comment.
Are you sure we need to document the command? Bower exist for a while so I expect people to know the command of how to install it as long as we document it's supported. We can't teach people how to use their tools, they should know what they are doing before using the library.
There was a problem hiding this comment.
It's not about teaching them their own tools, it's a convenience thing. I love it when it's done for me cause then I copy and paste the command knowing it'll work.
It's a mixture between commonplace and specificity.
There was a problem hiding this comment.
Yeah, I see. In this case, it's a tradeoff between convenience and adding more stuff to read. Besides, the README is pretty big already and there are some topics that direct you to links to reduce cluttering.
There are also arguments against copy/pasting code that also applies to commands, which might also be useful to people for learning purposes.
Do you think it's still worth adding this information here?
There was a problem hiding this comment.
Still waiting for the answer to the question:
Do you think it's still worth adding this information here?
There was a problem hiding this comment.
Yes, I think it's still worth it. While I agree with the ideology of the article, the whole purpose of this PR was to satisfy #332, so being explicit about the the available commands was apart of the fundamental focus.
| ``` | ||
|
|
||
| ```javascript | ||
| const Cookie = require('js-cookie'); |
There was a problem hiding this comment.
The link above sends the reader to #233 (comment). There there's a discussion on how to use it using the current mainstream tools.
Maybe we can document the ES6 module version because it's standard. But using code snippets for AMD might not be optimal since it occupies space in the README and it's a not standard thing.
We need to take care not to clutter the README with a lot of stuff. Maybe some of these could be in the Wiki?
There was a problem hiding this comment.
I completely agree with this point. Adding it to the README might be too much. Though it seems like too small of a segment to justify a click-away wiki article.
There was a problem hiding this comment.
So what's the conclusion?
There was a problem hiding this comment.
Since it's too small for it's own Wiki, my preference remains in the README.
|
+1 |
|
@austinpaquette Sorry to be so pedantic on this. It's that historically this project has invested a lot of effort to keep the README small, hope you understand. Here's an idea, what do you think about creating one PR for each command and leave it for people to leave feedback over time and in the end we decide which ones to land? Everybody could do it in the form for a "+1" reaction. Waiting for your feedback and thank you very much for this! |
|
@FagnerMartinsBrack completely understand, I'll probably sit down and do it tonight! |
|
Thanks @austinpaquette, good stuff! |
|
@austinpaquette Just pinging it back, did you manage to look at this? If not then I'll create a few issues to keep track of it. |
|
@austinpaquette I have created #349, #350, #351, #352, and #353. Waiting for community feedback. Why? Maybe Bower is not used a lot, maybe ES6 is getting traction, maybe CommonJS is used a lot, etc. It's hard to know if documenting something will have long lasting benefits. If they change the syntax of the tool or abandon it, then we'll still have to maintain the code snippet and change it here. These will allow us to have an idea of what to do and some evidence if it might be worth documenting. |
Closes #332
Just added the commands listed in the issue above to the readme, not dependant on any other branch feature and a simple change so I'm making the request directly for master.