Build router/traversal explainer by leveraging well-known terms

[lidel]

Extracted from #678 (comment)
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

[ElPaisano]

@DannyS03 scope questions:

• So is the task "create content explaining router/traversal concepts and write it so that well-known terms are used"?
• Are you proposing creating a new page for this in ipfs-docs? If so, what subsection? If not, what existing page are you proposing to update here?

[salmad3]

@ElPaisano right the idea was to create a new page as a general explainer for the process here of routing & traversal, under Concepts.

[ElPaisano]

@ElPaisano right the idea was to create a new page as a general explainer for the process here of routing & traversal, under Concepts.

@DannyS03 gotcha. This relates to the ongoing reorg / updates. A few thoughts here:

One of the goals of the reorg is to prune down the content in Concepts, for example #1433. So, I'd lean towards trying to slot this into existing material, if possible.

What I don't know: how much copy needs to be written here, so might be too much content for a paragraph or two.

Proposal: instead of creating a new page, could you could just add a blurb (maybe a paragraph or two) into the existing https://docs.ipfs.tech/concepts/libp2p/? Then link out to the much more detailed, thorough content for the subject in the libP2P docs (maybe https://docs.libp2p.io/concepts/nat/overview/ or something like that) "for further reading"?

Also, we recently updated https://docs.ipfs.tech/how-to/nat-configuration/#background - I'm not sure if any of this material would apply to what Lidel was requesting here

[salmad3]

thanks @ElPaisano, let's do that - as in, utilize the libp2p page and improve the references to the libp2p docs (as we also have more docs to refer to now which actually cover a good portion of the scope here).

[ElPaisano]

@DannyS03 👍 cheers

Seems like we can close this issue and combine it into #1431 (which you're already working on anyways). What do you think? Close this one out, copy the relevant info over to 1431, and create a PR?

[salmad3]

That sounds good @ElPaisano