Specs 2.0 & libp2p book

(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 (https://github.com/libp2p/specs/pull/96)
• yamux (https://github.com/hashicorp/yamux/blob/master/spec.md)
• secio (https://github.com/libp2p/specs/pull/106)
• Peer IDs (https://github.com/libp2p/specs/pull/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 (https://github.com/libp2p/specs/pull/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.

This is a broad roadmap covering libp2p wire formats, usage guidance, builtin protocols, NAT traversal, and multiaddr documentation. Start by reviewing the existing specs and referenced pull requests, then choose one unchecked document and confirm its scope with maintainers. Done means the selected Markdown document is clear, complete, and organized for the planned GitBook.