ipfs-docs
ipfs-docs copied to clipboard
Build router/traversal explainer by leveraging well-known terms
Extracted from https://github.com/ipfs/ipfs-docs/issues/678#issuecomment-792827654
It looks like network traversal is becoming a bigger and bigger thing within the web-3 space.
I believe using generic names to introduce new concepts usually improves onboarding and reduces fatigue due to cognitive overhead.
Peer and content routing in browser context is a fairly nuanced issue, but if we use well-known terms like STUN, ICE, TURN in the context of transports available in web browsers and/or go-ipfs running behind some types of NAT, that could help devs building on our stack to build proper mental model faster.
I am a bit thin on tangible details, but I'll use "nat traversal / browser transports / webrtc" problem space to give an example of what I mean:
- Introduce generic, well-known terms first
- Short explanation (one sentence max) and link to wikipedia/MDN will be enough – it either anchors following information to something developer knows, or makes a more junior dev aware that there is existing problem space to which our stack provides a solution.
- STUN, ICE, TURN, SDP or even more generic hole-punching, NAT-traversal etc.
- Then, introduce name of our solution or version of well-known concept. For example:
- "AutoNAT" provides STUN-like service for assisting hole-punching
- webrtc-star provides centralized service for exchanging SDP.
cc @vasco-santos @jacobheun @biglep @johnnymatthews