search

libp2p / docs

Documentation site for the libp2p project.
https://docs.libp2p.io/
Other
59 stars 88 forks source link

feat: noise #280

Closed salmad3 closed 1 year ago

salmad3 commented 1 year ago

Context

Latest preview

Please view the latest Fleek preview here.

salmad3 commented 1 year ago

thanks for the review, @MarcoPolo!

I don't see the value in the docs if we abstract the material to the point where we are generally only mentioning something along the lines of "this is a protocol, this is the protocol in libp2p, and this is the protocol ID" and not have context on how something works. However, I still agree that we should continue to abstract material that is primarily relevant to libp2p users.

What about an approach where we present more context on a subject matter in an optional dropdown menu. For example:

image

MarcoPolo commented 1 year ago

I don't see the value in the docs if we abstract the material to the point where we are generally only mentioning something along the lines of "this is a protocol, this is the protocol in libp2p, and this is the protocol ID". However, I also agree that we should continue to abstract material that is primarily relevant to libp2p users.

The most important things are:

  1. What is this thing at a high level, and where can I learn more about this thing?
  2. How does libp2p use this at a high level, and where can I learn more?
  3. How does this help me.

For Noise this would be:

  1. An encryption scheme that has been heavily reviewed and is used by Signal. learn more at https://noiseprotocol.org.
  2. libp2p uses this as a way to encrypt data between nodes and provide forward secrecy. See more at the
  3. This helps you send data end to end encrypted by default.

A user reading this doc should be able to understand how they would make use of this protocol. When I buy a hammer I only need to know which part I whack, not the process of making the hammer.

The problem with putting too much stuff in here is that then we need to review everything much more carefully. This turns the documentation into a spec rewrite. And makes it really brittle to any future changes. The higher level stuff targetting users is more likely to be true no matter what small changes we make. e.g. Noise will never not be used to encrypt your data end to end.

salmad3 commented 1 year ago

I hear you @MarcoPolo, thanks. I incorporated the suggestions.