Closed salmad3 closed 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:
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:
For Noise this would be:
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.
I hear you @MarcoPolo, thanks. I incorporated the suggestions.
Context
Latest preview
Please view the latest Fleek preview here.