30-seconds-of-code: [FIX] FIX NPM DOCUMENTATION

[kingdavidmartins]

[FIX] FIX NPM DOCUMENTATION

Description

I've realized on npm snippets are documented as the following

const dropRight = (arr, n = 1) => arr.slice(0, -n);

instead of the following

const seconds = require('30-seconds-of-code');
seconds.dropRight([1, 2, 3]); // [1,2]
seconds.dropRight([1, 2, 3], 2); // [1]
seconds.dropRight([1, 2, 3], 42); // []

I'm trying to start using more myself, and other people I've told about the package gave me the same feedback. It doesn't really show how to use the the module

Also Npm documentation doesn't have the following, so we have to update that as soon as possible too

⚠️ WARNING: Snippets are not production ready.

You can find a package with all the snippets on npm.

# With npm
npm install 30-seconds-of-code

# With yarn
yarn add 30-seconds-of-code

This way people who actually want to play with our snippets & use them in their projects can do so like so

Possible Solution

Was thinking of writing a script which create / updates a NPM folder with a README.md formatted with all of the following snippets documented accordingly for npm. Which Collaborators can just run and replace npm documentation weekly or daily Or if it uses our original README.md updating all our examples to show the following in the 2nd code block which shows our example

const dropRight = (arr, n = 1) => arr.slice(0, -n);

const seconds = require('30-seconds-of-code');
seconds.dropRight([1, 2, 3]); // [1,2]
seconds.dropRight([1, 2, 3], 2); // [1]
seconds.dropRight([1, 2, 3], 42); // []

Thoughts @Chalarangelo @skatcat31 @atomiks @fejes713

[Chalarangelo]

My thoughts are as follows:

• Repo/Website > npm Package. That being said any changes to the README that jeopardize the quality of the content on the repo even for brief periods of time are discouraged.
• The builder, if made to do this kind of thing, will definitely break and require micromanagement. Publishing to npm is not automated, so we will have to add flags and stuff to it that will sort of break the Travis build at places and will definitely end up with some edge-cases that will slow down builds.
• We are not encouraging people to use the package anyways, if they need it, they should read through the introduction to understand how to do so. If they are reading snippets and trying to understand them, it should be apparent that we do not encourage use of the package to begin with, so it'd be preferrable if they just copy-pasted the source code.
• The npm package hasn't gotten any downloads except from bots as far as we can tell, so unless some major traffic bump comes into play later down the line, it's never gonna be an issue we have to worry about. Most of our traffic and interest in the project comes from Github, to Github and mainly from people who want to learn some cool tricks, not just require a package that is clearly not meant to be used for the most part.

Based on my above points, I suggest we just leave everything as-is. If, by some coincidence, the npm package gets tons of traffic, these kinds of issues will organically end up in the issues list, as people who use the package will notice discrepancies and problems, so we will deal with those then. I know this is not proactive at all, but I do not have high hopes for the npm package from what we've seen so far, so it might never be an issue.

[skatcat31]

We should leave things as is or move to a name spaced example for nodeJS snippets

Previous art examples:

• http://ramdajs.com/docs/ shows a name spaced example without the require statement, just what it is commonly imported as for the sake of documentation
• http://underscorejs.org same as above
• https://github.com/cheeriojs/cheerio same as above

So if we want to adopt a method for the nodeJS snippets, it would be either leave them the same, or only put the example package namespace shown in our NodeJS import example.

I am ambivalent to this though( will not offer a vote myself ) since if a developer doesn't know how to modify an example to work in their environment they are strictly a beginning developer in my eyes and should ask for help. Other developers would be slightly annoyed they have to modify them but that shows they aren't as advanced as they think if they can't change their import to import that specific set of methods they'll be copying examples for into the namespace since all of our methods are standalone( const {droptRight} = import('30-seconds-of-code') )

[fejes713]

The npm package hasn't gotten any downloads except from bots as far as we can tell, so unless some major traffic bump comes into play later down the line, it's never gonna be an issue we have to worry about. Most of our traffic and interest in the project comes from Github, to Github and mainly from people who want to learn some cool tricks, not just require a package that is clearly not meant to be used for the most part.

I totally agree with @Chalarangelo, personally, I am not sure how much work needs to be done but right now this is not urgent, and @skatcat31 also has a point in this. Take my vote to be neutral, and do as you want to.

I suggest that we keep this in mind, as this repo will, hopefully, get lots of traffic sometimes in the future 👍

[Chalarangelo]

As far as I can tell most of us are against these changes. I'm closing, but feel free to comment or reopen the issue if you want to discuss this further.

[lock[bot]]

This thread has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for any follow-up tasks.