docs: reorganize the networking section#16646
Conversation
056e55c to
b3a1612
Compare
|
Utilmately, I don't think this succeeds as a reorganization because it mostly grafts new content into the existing heirarchy. The new content ends up repeating information from the old content (e.g. "STUN and NAT" vs. "Underlying networking stack"). I think we need to take a hostic view of these docs and how the content should be presented. @bpmct presented some opinions about the ordering, but it needs to be expanded to include how all the existing material is incorporated into a new heirarchy. |
| [Tailscale's open source](https://tailscale.com) backs our websocket/HTTPS | ||
| networking logic. | ||
| [Tailscale](https://tailscale.com)'s implementation of | ||
| [Wireguard](https://www.wireguard.com/) backs our websocket/HTTPS networking logic. |
There was a problem hiding this comment.
It's not just Wireguard, so this statement is misleading. It's too complex at this stage to explain which exact pieces of Tailscale we've embedded, though. Perhaps:
Coder establishes network connections with an embedded version of Tailscale's open source data plane.
There was a problem hiding this comment.
there was some discussion recently about how to be more clear about the Wireguard and Tailscale implementations because it has led to some confusion (I can't find the issue I'm thinking of, but I see #16792 came up recently, which is different, but maybe related to how people think of the implementation when they hear "Tailscale")
I also agree that if it's more in-depth than we can squeeze into a sentence or two, we should use the simple description and link off to somewhere we explain it better. That can be the "201" section, and for now, I just used your copy and think the followup PR(s) should include that better explanation
| }, | ||
| { | ||
| "title": "More", | ||
| "description": "More about networking", |
There was a problem hiding this comment.
Can we avoid being so generic here? It seems a shame to hide two titles that give a reasonable idea of what they are behind a "More" that tells you nothing.
There was a problem hiding this comment.
definitely yes - current copy is a bit of a placeholder while we work through what the next page or pages entail(s)--like writing an intro after the rest of the essay, we'll be able to give it a succinct description once we know what story we're trying to tell.
| [Premium](https://coder.com/pricing#compare-plans) feature that allows you to | ||
| provide low-latency browser experiences for geo-distributed teams. | ||
|
|
||
| ### Direct connections |
There was a problem hiding this comment.
Direct vs relayed connections are not a sub-topic of Geo-distribution. They are fundamental to how Coder networking operates, even in a single geographic region.
@spikecurtis @bpmct - I see this PR as our first move at separating the 101 from the 201+ and I can see it going through three stages:
I'm re-reading this and it seems like I'm trying to disagree without disagreeing, but I think the theme I'm going for is more "yes, and" - since there are so many rabbit holes we could follow, let's treat it holistically and let's err on the side of more PRs/iterations. I hope this also gives us a chance to solicit more contributions from the team |
|
from @deansheather (🙌 ) on support ticket
|
I don't agree that this PR succeeds on those terms. The sections don't make sense to me, and it doesn't closely follow Ben's 101, 201, etc progression. Let's schedule a time to chat with me, @EdwardAngert and @bpmct -- possibly during our Architecture Review Board meeting. |
|
reopen and start with 101
|
closes #16634
preview