Create spec legend and terminology guideline

[SgtPooki]

Summary

To prevent the confusion of terminology when reading specs, we should use consistent language and provide a document similar to https://github.com/libp2p/specs/blob/master/00-framework-02-document-header.md that spec-writers can use to ensure language across specs is consistent and clear.

Description

I’ve only read two libp2p specs so far, but I think the specs could be clearer if we started using consistent terminology for peers and streams in our spec descriptions.

e.g.

• “initiator” is okay, but “receiver” is confusing since the “initiator” frequently receives messages.
• "initiator" can be confusing the more operations the spec has because there may be separate initiators of connections or streams within a protocol
• in specs, “peer A” vs “peer B” — “stream A” vs “stream B” — “connection A” vs “connection B” can be very difficult to track while parsing a spec because there is no contextual definition.

I could not find existing guidelines or recommendations for writing legends or using terminology in libp2p specs. I think solidifying a guideline for the terminology in libp2p specs would help spec readers.

Proposal

We could create a single global legend (for naming of peers in a spec) but we will need individual legends per spec to define contextually relevant names for streams/connections/messages.

• Create https://github.com/libp2p/specs/blob/master/00-framework-03-document-terminology-legend.md that contains global names that should be consistent across specs.
  • Global names should probably include standardized names for: Protocol initiators, Connection initiators, Stream initiators
  • provide guidance for each spec to add additional legends specific to their spec, for streams, connections, and any non-globally-relevant terms.
• Prohibit any names that apply to both sides of a conversation. e.g. "receiver" quickly becomes confusing in a p2p conversation. "initiator" is also confusing because multiple things can be initiated: streams, connections, protocol handling, etc.
• Advise against any "A", "B", "1", or "2" names
  • Using semantic naming makes discussions and contextual awareness much simpler on readers. e.g. "Stream 1" and "Stream 2" are much harder to track in a complicated protocol than "Negotation-stream" and "Goal-stream". see Stream Migration Protocol #328 (comment)

Example

Term	Definition
Leader	The Peer who begins/initiates the connection with the Participant peer
Participant	The Peer who receives/acknowledges the connection and streams with the Leader peer
Negotiation-stream	An initial stream created in an existing connection between Leader and Participant peers.
Goal-stream	A new stream, using an "upgraded" transport when compared to the Negotiation stream, created on a new connection between leader and participant peers.

References to confusion/assumptions around terminology

• Add a Stream Migration spec #406 (comment)
• Add a Stream Migration spec #406 (comment)

[mxinden]

Thank you for the detailed suggestion.

I am not opposed to this proposal. Definitely see the value for consistent and descriptive naming.That said, I don't have the priority to push this forward any time soon. In case you do, happy to help along the way.