libp2p / libp2p/specs

Feedback from users on spec format and accessibility

Open
#126 1 comment 3 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
No language data
Stars
1.8k
Forks
320
Avg merge
11d 15h
Merged PRs (30d)
1

Description

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.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Begin with the current gossipsub spec, focusing on its terminology, algorithmic definitions, data structures, and RPC behavior. Compare the requested glossary, implementers' guide, pseudocode, diagrams, and floodsub/meshsub/randomsub discussion; completion would require an agreed accessibility scope and concrete spec changes.

Written by the indexing model from the issue text.

Assessment

Domain
documentation, networking
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.