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.

Ultimately, I don't think this succeeds as a reorganization because it mostly grafts new content into the existing hierarchy. 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 holistic 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 hierarchy.

@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:

1. (this PR) Separate the intro/getting started from the more complex - give the sections places to live that make sense

2. Develop the intro into what people often ask for, and deliver it in a digestible, friendly landing page doc

3. Build out the more in-depth descriptions and next-level structure. This can happen at the same time as -2, but I'm listing it separately so that neither one blocks the other.

   There's a lot that we can dive deeper into in terms of more advanced networking questions, and I want to be able to treat them as sections.

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

• workspace proxy

  We recommend having the workspace nodes as close to the user as possible, then putting workspace proxies in the same datacenter as the workspace nodes. Just keep in mind that the round-trip time for proxied connections isRTT(user <=> proxy) + RTT(proxy <=> workspace), so you want to keep both as low as possible

• control plane considerations

  It's fine if the control plane is in a separate region to workspaces. Just keep in mind that the control plane performs the functions of a workspace proxy, so the same RTT argument applies. CLI connections will try all proxies to determine the best one to use

• how does DERP fit into this

  DERP is a relay protocol that lets the client exchange wireguard packets with the agent. It's used if the two peers can't establish a direct UDP connection for whatever reason (usually firewalls or NATs). The control plane and workspace proxies act as a DERP server, so in the cases that direct connections can't be established all data will flow through the control plane or a proxy.

  You can tell if you're connected directly (aka. p2p) or which DERP you're connected to usingcoder ping $workspace

(this PR) Separate the intro/getting started from the more complex - give the sections places to live that make sense

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

• inbound/outbound port reqs (what ports need to be open on the deployment)