Feedback from users on spec format and accessibility
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
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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