docs: review getting started

[jacobheun]

This PR is to supplement review of #514

[vasco-santos]

I think that we should have at least part of this. Explicitly say that configuring js-libp2p should be an iterative process rather than a let's configure everything before running

[jacobheun]

To me this read like, "The libp2p setup is more than a one time thing, you're never done configuring libp2p". It sounds daunting.

It sounds like you meant something more like:

If you're new to libp2p, we recommend configuring your node in stages, as this can make
troubleshooting configuration issues much easier. In this guide, we'll do just that. 
If you're more experienced with libp2p, you may wish to jump to the [Configuration readme](#).

[vasco-santos]

Yes, I think that is a better way of putting this! Can you change to that in this PR?

[jacobheun]

Added that in.

[vasco-santos]

I added this because I think we should guide people to use the API and CONFIGURATION docs, because as soon as they are experienced with js-libp2p, they should go through those docs instead

[jacobheun]

Since the main readme is the landing page for most users I think it makes sense to have that distinction there. My concern with recommending people go read configuration first is that can be an overwhelming amount of information. We should help users get started quickly, and then send them to docs that will build on what they've learned here, and help them customize their nodes.

[vasco-santos]

I agree that it can be overwhelming to recommend people to read configuration first.
My idea here is to point them to subsections of the other documents, instead, of all document. So I agree with you on the configuration part, but I think we should keep the pointer do ./API.md#create

[jacobheun]

I added the link back to the first mention of create.

[terichadbourne]

Just some quick feedback after skimming through #514 at @vasco-santos's request. My main question is where you expect people to be coming from when they get here and what they need to have already read in order for this Getting Started guide to make sense. (I recommend adding links to prereqs if they exist.)

Personally, having very little libp2p knowledge, I appreciated the little paragraphs at the start of each section but wished there were more of that context. I'm sure there are others who'd want less of it and more direct jumps into the lines of code needed to make things happen.

I went to the main readme of this repo to see if it had the context I was looking for and it didn't. It did point to a ton of different websites for reference, with this disclaimer:
We are in the process of writing better documentation, blog posts, tutorials and a formal specification. Today you can find:
which felt like "here's a list of our subpar docs; good luck!" (totally underselling what you do have available). I would have preferred to see that list prefaced with a "Here are our docs" and a note next to each one about what type of info I could info at that site, followed up with a "We're always improving our docs and we'd love your help" call to action.

https://docs.libp2p.io/ turned out to have just the kind of explanations I was looking for, and looks very professional to boot, so it might make sense to link from certain sections here in the js-libp2p getting started guide to the concept explainers over there for those who'd like more background.

[vasco-santos]

Thanks for your time @terichadbourne

Just some quick feedback after skimming through #514 at @vasco-santos's request. My main question is where you expect people to be coming from when they get here and what they need to have already read in order for this Getting Started guide to make sense. (I recommend adding links to prereqs if they exist.)

I expect them to come from: libp2p/js-libp2p/refactor/async-await#usage. Maybe before tutorials and examples. I think that we would not have prereqs here, people would have to know JS, as well as some concepts of networking, but when they come to a lib like this, I think that it is already implicit.

Personally, having very little libp2p knowledge, I appreciated the little paragraphs at the start of each section but wished there were more of that context. I'm sure there are others who'd want less of it and more direct jumps into the lines of code needed to make things happen.

@jacobheun what do you think on adding toggles with "more details" for people to click and the section introductions would be available? I agree with teri that this introduction might be important to some people, but I also think if might be noisy for people that prefer to directly look into code.

I went to the main readme of this repo to see if it had the context I was looking for and it didn't. It did point to a ton of different websites for reference, with this disclaimer:
We are in the process of writing better documentation, blog posts, tutorials and a formal specification. Today you can find:
which felt like "here's a list of our subpar docs; good luck!" (totally underselling what you do have available). I would have preferred to see that list prefaced with a "Here are our docs" and a note next to each one about what type of info I could info at that site, followed up with a "We're always improving our docs and we'd love your help" call to action.

My idea is to simply remove that and reference my proposal on libp2p/js-libp2p#512#issuecomment-564929701

https://docs.libp2p.io/ turned out to have just the kind of explanations I was looking for, and looks very professional to boot, so it might make sense to link from certain sections here in the js-libp2p getting started guide to the concept explainers over there for those who'd like more background.

In this document, we reference parts of CONFIGURATION.md which have references to the docs as you suggested. I know that people need to navigate from Getting started to Configuration to docs website, but I prefer that approach rather than having those references to the docs website in both, as it would introduce a lot of noise in the documentation. Other option is to move those reference links to the Getting started, but I think they are more useful next to the Configuration part of things. Let me know your thoughts

[jacobheun]

@jacobheun what do you think on adding toggles with "more details" for people to click and the section introductions would be available? I agree with teri that this introduction might be important to some people, but I also think if might be noisy for people that prefer to directly look into code.

I think we can do lead ins to each section with a brief introduction to what we're building and why we needed. I don't think this needs to be more than a few sentences. I think we should follow those with "read more" links to docs.libp2p.io. That would enable us to focus on keeping those docs up to date, and avoid duplicating that information here if we don't need to.

I think the goal should be for users have just enough information to get them started and
for them to understand what they're doing, with clear calls to more information for people who want to learn more about that topic, or specific js usage.

For example, when I start adding the code for Transports, I should understand that they are the components of libp2p that do they actual communicating between nodes, and if I was so inclined, should have easily been able to read up more on transports at https://docs.libp2p.io/concepts/transport/. I think having each section end with a "call to action" for users to see more about configuring that component in the Configuration readme, and the API where it makes sense, will go a long way in creating a nice starting point for new users, and existing users.

[vasco-santos]

Let's just get this merged to the other PR, so that I can iterated on the stuff we discussed

[jacobheun]

@vasco-santos sounds good, added your changes, fill free to merge if it looks good.