docs icon indicating copy to clipboard operation
docs copied to clipboard

Improve Protocol Documentation.

Open finlaydotb opened this issue 3 years ago • 3 comments

First of all, thanks for the documentation. I appreciate the effort that goes into it. Thing is, I just read the protocol section in the documentation here and I have to say it leaves me with more questions than answers.

What I got from it is basically that protocol allows nodes to communicate in a particular way. But I know that already from it being called protocol and I do not have to read the piece. The information about protocol Ids and protocol negotiation also does not provide much value.

I think what I am missing is:

  • What is a structure of a protocol in libp2p? What interface does it provide, what are the rules to follow etc
  • Do not just list examples of inbuilt protocol (Ping, Identify, secio etc) but show how to use them and relate it to the interface they provide.
  • And maybe an advance section that quickly shows how to write a custom protocol.

I think the documentation on protocol will be improved is these points are taken into consideration.

finlaydotb avatar Dec 22 '21 14:12 finlaydotb

Thanks for the feedback! We'll probably rewrite this soon so we'll keep this in mind. Do you think you would prefer a more tutorial-like version of this doc? Also if you have ideas here we're happy to review contributions.

MarcoPolo avatar Jun 24 '22 16:06 MarcoPolo

Will address this in protocol rewrite by @DannyS03 or @p-shahi

p-shahi avatar Aug 26 '22 15:08 p-shahi

Also address

This is a proposal for a tutorial to follow the current ["Getting Started"](https://docs.libp2p.io/tutorials/getting-started/) tutorials based on what I would have found useful as I've been getting to know libp2p in the last week or so.

The tutorial would be called "Implementing a Protocol" and would cover:

- Defining a protocol ID and setting a stream handler
- Reading and writing protocol data
- Defining a set of structured messages that make up the protocol
- Encoding / decoding protocol messages
- Handling different types of messages
- Handling an async request / response flow
- Handling protocol upgrades (i.e. version bumps, semver matching)

Rather than making up a protocol, I suggest using an existing, simple protocol that's easy to understand and doesn't distract from the point of the tutorial, perhaps [JSON-RPC](https://www.jsonrpc.org/specification) over libp2p?

@yusefnapora WDYT? I'd be happy to draft a Go version of this if you think it would be useful? I always like sharing my learning experience to make it easier for others 😄 

https://github.com/libp2p/docs/issues/46

p-shahi avatar Aug 26 '22 15:08 p-shahi