Specs 2.0 & libp2p book

[ghost]

(some preliminary brainstorming based on a discussion with @whyrusleeping, @bigs)

Goal

Revise/update/improve libp2p specs and provide clearer usage guidance

List of proposed documents

1. Base wire formats

• multistream select
• multiplex (Add specs for mplex #96)
• yamux (https://github.com/hashicorp/yamux/blob/master/spec.md)
• secio (SECIO spec #106)
• Peer IDs (docs: add peer id spec #100)

2. libp2p book / Usage

(some of these could be considered specs, others would be non-mandatory "suggested usage" guides)

• a doc describing exactly how these are tied together, a spec for the ‘swarm’
• document describing how dialing works.
• document describing the ‘libp2p api’. Which is not language specific, but a broader description of the capabilities of each subsystem in terms of what it does.
• Better diagrams (see https://github.com/libp2p/libp2p/issues/55)

3. Libp2p ‘builtin’ protocols

• Identify
• Ping
• pubsub
• DHT (Add minimal Kademlia DHT spec #108)
• Relay

4. Other

• probably also something on NAT Traversal
• Also need a multiaddr spec (there may exist one, but lets make sure its "proper")

Format notes:

• Everything in markdown, organized into a gitbook. Gives us a nice website UI, or users can print it all to a single PDF.

[raulk]

The non-normative technical walkthrough I'm writing covers these topics. @yusefnapora is working on docs.libp2p.io. We have docs under control -- we just need to get specs aligned now.