shresthagrawal / learnp2p

https://learnp2p.org
https://jslibp2p-chat-tutorial.vercel.app
MIT License
26 stars 6 forks source link

Content updates for multiaddr/bootstrap section. #14

Closed acolytec3 closed 4 years ago

acolytec3 commented 4 years ago

Flesh out all the content for the multiaddress/bootstrap node section of the tutorial. All of these updates are based on v0.28 of js-libp2p so we'll need to update all the code as well once #11 is merged since the tutorial code is all written in 0.25 and way out of date.

0xjjpa commented 4 years ago

@shresthagrawal can we get something like vercel up and running so we can quickly see how previews would look like? Let me know if you need help setting it up.

vercel[bot] commented 4 years ago

This pull request is being automatically deployed with Vercel (learn more). To see the status of your deployment, click below or on the icon next to each commit.

🔍 Inspect: https://vercel.com/shresthagrawal/jslibp2p-chat-tutorial/axp5q6mzg ✅ Preview: https://jslibp2p-chat-tutorial-git-fork-acolytec3-master.shresthagrawal.vercel.app

shresthagrawal commented 4 years ago

Also I noticed that you haven't written anything in the introductory page https://jslibp2p-chat-tutorial-4xmtj3868.vercel.app/#/2/introduction

acolytec3 commented 4 years ago

@shresthagrawal I've added an intro section and made updates based on your feedback.

shresthagrawal commented 4 years ago

@acolytec3 nice work! can you have a look into the preview and check the following points:

acolytec3 commented 4 years ago

@acolytec3 nice work! can you have a look into the preview and check the following points:

  • The intro page doesn't has a bold heading
  • It doesnt has the connecting flow between the first chapter all some information in redundant
  • if you think you can move some stuff from chapter 1 to intro that could be good
  • I really wanted the users to understand why is the multiaddrs is future proof. So would be nice to elaborate by an example like if there was a new protocol xyz multi addrs will still support it in the following way.

I did a major overhaul of intro and section 0 along these lines. Check the latest and let me know what you think.

vasa-develop commented 4 years ago

For the peer identity page, I think a more natural way to introduce multiaddress is to first point out the problems with the current system. The way it is written now is more about showing some facts (like starting with how multiaddress is structured), rather than starting by addressing the problems with the current addressing system. Discussing problems makes the reader reason about what is wrong today and why the multiformats build in the way it is.

See the why do we need multiformats part of this article.

acolytec3 commented 4 years ago

For the peer identity page, I think a more natural way to introduce multiaddress is to first point out the problems with the current system. The way it is written now is more about showing some facts (like starting with how multiaddress is structured), rather than starting by addressing the problems with the current addressing system. Discussing problems makes the reader reason about what is wrong today and why the multiformats build in the way it is.

See the why do we need multiformats part of this article.

Totally makes sense. If you're good with the technical content here, we'll incorporate this feedback into the additional updates we're going to make to bring in the narrative structure and can explain those issues in the narrative.