Feedback from users on spec format and accessibility

[raulk]

Just chatted with @mikerah today, and she had the impression that our specs are targeted at audiences with significant pre-existing P2P background. In the call, there was general consensus that this should not be the case; specs should be accessible to technical audiences with no specialised background.

IMO, a good archetype for accessibility could be the HTTP 1.1 spec.

Some improvement ideas:

• Glossary at the end of each spec: defining terminology or terms that the author is using but have no industry-wide consensus (e.g. ambient).
• Implementers' guide: to be clarified (@mikerah).
• Much more pseudocode, especially for the algorithmic definitions.
• Comparative content. For example, in the current gossipsub spec, we could do with a comparison between floodsub, meshsub, randomsub, gossipsub in terms of use cases, dissemination patterns, etc.
• Diagrams; in the context of gossipsub, how do all the data structures (peers, window, etc.) relate to one another; how RPCs affect state; a control flow chart for the heartbeat algorithm, etc.

[Mikerah]

The implementers' guide would be for guiding implementers' implementing their versions of various specifications of the libp2p spec. This would allow some details to be decided by the implementer without restricting the design space of the libp2p specifications. It should contain advice, recommendations and gotchas that implementers should take into account.

Here's an example from the IETF for an implementers' guide: https://tools.ietf.org/html/draft-ietf-ipp-implementers-guide-v11-01