Create spec legend and terminology guideline

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 https://github.com/libp2p/specs/issues/328#issuecomment-1668515529

Example

References to confusion/assumptions around terminology

• https://github.com/libp2p/specs/pull/406#issuecomment-1100654684
• https://github.com/libp2p/specs/pull/406#discussion_r857332590

Start by reviewing 00-framework-02-document-header.md and the terminology discussions linked from issue 565, including issue 328 and pull request 406. Create 00-framework-03-document-terminology-legend.md with global peer, connection, and stream terminology, guidance for spec-specific legends, and the proposed naming recommendations; done means the checklist is addressed in a clear, usable document.