[Documentation] "Install" section in README does not make sense

[mcclure]

Say I am new to libp2p and just want to install whatever npm package I need to get started so I can run example code in tutorials. I come to the js-libp2p page on github. I look under "Install". It gives the npm line to run to install, then says,

this module is only a skeleton and should not be used directly other than libp2p bundle implementors that want to extend its code

So… wait. I shouldn't install it? The line is unclear; it says "don't use", not "don't install".

It also says "as noted above" so I look above. Above it nicely explains that I should use "libp2p-ipfs-nodejs" or "libp2p-ipfs-browser". Great! I'll install one of those. Except those links are links to… javascript files? I search the npm registry. There is no "libp2p-ipfs-browser" there. There is a "libp2p-ipfs-nodejs" but it is marked "deprecated" with a big banner that says to go to… github.com/libp2p/js-libp2p, in other words this page. Later the README suggests I "create my own" libp2p "bundle" but it doesn't explain what thing or collection of things I need to install to create one of those. I don't know exactly what a "bundle" is at this point.

It is clear I am probably looking at the wrong page. Unfortunately you are the top hit on Google for "javascript libp2p". So you have a page which is clearly not the first thing a new user should look at, but because of Google you are the first thing a new user is likely to look at, and you don't link which page within the sprawling libp2p web presence is the first thing a new user should look at.

My "expected behavior"/suggestion is that you change "this module… should not be used" to "this module… should not be installed" (if that is what you mean), and that you provide links in the install section to one of:

• What to install instead
• What document I should read to understand that "what should I install instead?" is a nonsensical question
• If you're going to suggest using the "libp2p-ipfs-nodejs" or "libp2p-ipfs-browser" "bundles", you should say what package(s) to install to use those two "bundles".

"Type: Very Low - Translation or documentation mistake. Something that won't give anyone a bad day." My day is ok so far

(Maybe this is redundant with #231. But that issue is over a year old so maybe resolving #231 is hard and it's worth addressing the smaller problem that you have a "install" section that is not actionable.)

[jacobheun]

@mcclure thank you for the write up, it's very helpful hearing your experience attempting to get up and running. We are currently finishing up work on the async/await refactor and part of this is rewriting the readme. I would like to include a Getting Started section / standalone readme that covers what modules to install and how to use them for both (Node.js and the Browser).

We are targeting to have a pre release of the refactor early this week, which we will have initial docs ready for.

As the final release of the refactor is likely a few weeks out, I think it would still be valuable to do a quick pass to remove the confusing language and give more direction on how to install modules needed for creating your own bundle

[mcclure]

Thanks!

This is the wrong place to ask this, but while I have your attention, a minor related question— are the files in examples/ covered by the same LICENSE as the library?

[jacobheun]

Yes, they're under the same license.

[vasco-santos]

@mcclure I created a PR where I go into detail regarding libp2p configuration.

Could you please have a look and provide feedback? 😄

Other than this, I will be creating a getting started guide, where I will go through this doc, and talk about what to install among other important introductory stuff

[vasco-santos]

With the docs mentioned during this issue done, this should be improved.