Merge pull request #6 from n0-computer/rae/docs-review2

okdistribute · web-flow · commit 1c5756054d8e · 2025-12-15T15:20:19.000-08:00
remove reliance on p2p language
diff --git a/concepts/discovery.mdx b/concepts/discovery.mdx
@@ -29,7 +29,7 @@ There are four different implementations of the discovery service in iroh. **By
 We want iroh to establish connections with as little friction as possible. Our
 first big push toward chipping away at this goal was adding [holepunching](/concepts/holepunching) into
 iroh. Now, devs no longer need to worry about opening up ports on their servers
-/ firewalls or be resigned to only creating peer-to-peer connections to
+/ firewalls or be resigned to only creating connections to
 computers inside their local NAT.
 
 But even with holepunching, you need to know *where* to dial. Dialing an endpoint in
diff --git a/concepts/endpoints.mdx b/concepts/endpoints.mdx
@@ -3,22 +3,22 @@ title: "Endpoints"
 ---
 
 An _endpoint_ is the main API interface to create connections to, and accept
-connections from other iroh endpoints. The connections are peer-to-peer and
+connections from other iroh endpoints. The connections are 
 end-to-end encrypted. Endpoints have a `EndpointID` (the public half of an
 Ed25519 keypair) and the private key used to sign and decrypt messages.
 
 Generally, an application will have a single endpoint instance. This ensures all
-the connections made share the same peer-to-peer connections to other iroh
+the connections made share the same connections to other iroh
 endpoints, while still remaining independent connections. This will result in
 more optimal network behaviour.
 
 
 ## Connections
 
-Because we're in a peer-to-peer context, either endpoint might be operating as
-the "server", so we use `connect` and `accept` to distinguish between the two.
-The `connect` method is used to create a new connection to a remote endpoint,
-while `accept` is used to accept incoming connections from a remote endpoint.
+Either endpoint might be operating as the "server", so we use `connect` and
+`accept` to distinguish between the two.  The `connect` method is used to create
+a new connection to a remote endpoint, while `accept` is used to accept incoming
+connections from a remote endpoint.
 
 Connections are full-fledged QUIC connections, giving you access to most
 features of QUIC / HTTP3, including bidirectional and unidirectional streams.
diff --git a/concepts/holepunching.mdx b/concepts/holepunching.mdx
@@ -10,16 +10,14 @@ Imagine you're trying to video call a friend. Both of you are behind routers at
 home. When you try to connect directly to each other, your routers' firewalls
 block the incoming connection because they don't recognize it as a response to
 something you requested. The combination of NAT (which translates addresses) and
-firewall rules (which filter traffic) makes direct peer-to-peer connections
+firewall rules (which filter traffic) makes direct connections
 challenging.
 
 Traditionally, this problem was solved by:
 - **Port forwarding**: Manually configuring your router to allow specific connections (tedious and requires technical knowledge)
 - **Relay servers**: Routing all traffic through a third-party server (slow and expensive)
 
-Neither solution is ideal for peer-to-peer applications.
-
-## The Solution: Holepunching
+## The Innovation: Holepunching
 
 **Holepunching** is a clever technique that works around NAT and firewall restrictions to allow direct connections between peers without manual configuration or relying entirely on relay servers.
 
diff --git a/concepts/protocols.mdx b/concepts/protocols.mdx
@@ -7,12 +7,14 @@ behavior. Once you've established an iroh connection, protocols determine what
 happens next: transferring files, syncing documents, broadcasting messages, or
 whatever your application needs.
 
-iroh provides the encrypted, peer-to-peer connections - protocols define what to
+iroh provides the pool of encrypted QUIC connections - protocols define what to
 do with them.
 
 ## Peer-to-peer protocols
 
-Unlike HTTP's client/server model where one side only sends requests and the other only responds, peer-to-peer protocols typically support **both** initiating and accepting connections on the same endpoint.
+Unlike HTTP's client/server model where one side only sends requests and the
+other only responds, peer-to-peer protocols typically support **both**
+initiating and accepting connections on the same endpoint.
 
 This means:
 - Any peer can request data from any other peer
diff --git a/concepts/relays.mdx b/concepts/relays.mdx
@@ -37,7 +37,7 @@ Relay code is open source! You can run your own relay server, or [pick a hosting
 provider](https://n0des.iroh.computer).
 
 
-### Why this architecture is powerful
+## Why this architecture is powerful
 
 This approach makes uptime management significantly easier compared to
 traditional client-server architectures:
diff --git a/concepts/tickets.mdx b/concepts/tickets.mdx
@@ -62,7 +62,7 @@ The postcard encoding keeps tickets compact despite containing multiple pieces o
 
 ## Security considerations
 
-**Tickets contain IP addresses**: When you create a ticket, it embeds the IP addresses you're currently reachable at. Sharing a ticket means sharing your IP address with whoever receives it. This is intentional - it enables direct peer-to-peer connections without a central server.
+**Tickets contain IP addresses**: When you create a ticket, it embeds the IP addresses you're currently reachable at. Sharing a ticket means sharing your IP address with whoever receives it. This is intentional - it enables direct connections without a central server.
 
 This is actually *better* than many P2P systems that broadcast your IP to all peers. With tickets, you form a "cozy network" between peers you explicitly choose to connect with.
 
diff --git a/connecting/creating-endpoint.mdx b/connecting/creating-endpoint.mdx
@@ -6,14 +6,8 @@ An endpoint is the core building block of an iroh node. It manages network
 connections, handles incoming and outgoing traffic, and provides the necessary
 infrastructure for implementing protocols.
 
-Once you have an Endpoint, you can use it to create connections or accept incoming connections from other endpoints.
-
-Unlike HTTP servers, which listen on specific ports, iroh Endpoints use a peer-to-peer
-model to establish connections. This means that endpoints can connect directly
-to each other without relying on a central server.
-
-This means that endpoints can be more resilient to network issues and can operate in
-a wider range of network environments.
+Once you have an Endpoint, you can use it to create connections or accept
+incoming connections from other endpoints. 
 
 ## Creating an Endpoint
 
diff --git a/deployment/dedicated-infrastructure.mdx b/deployment/dedicated-infrastructure.mdx
@@ -8,7 +8,7 @@ DNS and end-to-end encryption over relays. This infrastructure comprises:
 1. [Relays](/concepts/relays)
 2. [Discovery Servers (DNS)](/concepts/discovery)
 
-Relays forward traffic when direct peer-to-peer connections are not possible as well
+Relays forward traffic when direct connections are not possible as well
 as facilitates holepunching for direct connections. These servers are managed and
 maintained by [the n0 team](https://n0.computer), and are shared by a global public network of
 developers.
diff --git a/deployment/wasm-browser-support.mdx b/deployment/wasm-browser-support.mdx
@@ -28,8 +28,10 @@ This is because we can't port our hole-punching logic in iroh to browsers: They
 Keep in mind that *connections are end-to-end encrypted*, as always with iroh.
 So even though traffic from browsers is always relayed, it can't be decrypted by the relay.
 
-There are other ways of getting peer-to-peer connections going, such as WebTransport with `serverCertificateHashes`, or WebRTC.
-We may expand iroh's browser support to make use of these to try to generate fully peer-to-peer connections even when a browser node is involved in the connection.
+There are other ways of getting direct connections going, such as WebTransport
+with `serverCertificateHashes`, or WebRTC.  We may expand iroh's browser support
+to make use of these to try to generate direct connections even when a browser
+node is involved in the connection.
 
 ### `iroh` crate features
 
diff --git a/docs.json b/docs.json
@@ -21,6 +21,7 @@
               "examples/examples",
             {
               "group": "How it works",
+              "expanded": true,
               "pages": [
                 "concepts/endpoints",
                 "concepts/tickets",
@@ -43,7 +44,7 @@
             ]
           },
           {
-            "group": "Communicating over Iroh",
+            "group": "Building your App",
             "pages": [
               "protocols/kv-crdts",
               "protocols/blobs",
diff --git a/examples/chat.mdx b/examples/chat.mdx
@@ -1,10 +1,13 @@
 import { YouTube } from '@/components/youtube'
 
-## Building a P2P Chat Application with Iroh
+## Building a Chat Application with Iroh
 
 <iframe width="560" height="315" src="https://www.youtube.com/embed/ogN_mBkWu7o?si=Y-GqkmGBRZfRhclc" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
 
-This tutorial demonstrates how to build a peer-to-peer chat application from scratch using Rust and the Iroh library. While this implementation is simplified, it illustrates core concepts of P2P networking and the Iroh gossip protocol.
+This tutorial demonstrates how to build a peer-to-peer chat application from
+scratch using Rust and the Iroh library. While this implementation is
+simplified, it illustrates core concepts of the iroh gossip
+protocol.
 
 The code in the above video differs slightly from the code presented below. We recommend watching the video and following along until you get comfortable. When you are ready for a deeper dive into the code, walk through this tutorial.
 
diff --git a/examples/examples.mdx b/examples/examples.mdx
@@ -9,7 +9,7 @@ title: "Examples"
     icon="image"
     href="https://www.iroh.computer/sendme"
   >
-    Sendme will connect your devices directly & transfer files peer-to-peer, 
+    Sendme will connect your devices directly & transfer files, 
     without any accounts or configuration.
   </Card>
   <Card
@@ -32,7 +32,7 @@ title: "Examples"
     icon="gamepad"
     href="https://github.com/tipragot/godot-iroh)"
   >
-A peer-to-peer multiplayer extension for Godot based on iroh.    
+A multiplayer extension for Godot based on iroh.    
   </Card>
   <Card
     title="iroh-lan"
diff --git a/index.mdx b/index.mdx
@@ -1,6 +1,6 @@
 ---
 title: "Introduction"
-description: "iroh establishes direct peer-to-peer connections whenever possible, falling back to relay servers if necessary. Get fast, cheap, reliable connections that are authenticated and encrypted end-to-end using QUIC."
+description: "iroh establishes direct connections whenever possible, falling back to relay servers if necessary. Get fast, cheap, reliable connections that are authenticated and encrypted end-to-end using QUIC."
 ---
 
 ## Setting up
@@ -27,7 +27,7 @@ composable, so you can pick and choose what you need.
     icon="image"
     href="/protocols/blobs"
   >
-    Store and transfer large binary files peer-to-peer.
+    Store and transfer large binary files.
   </Card>
   <Card
     title="Key-Value CRDTs"
@@ -41,7 +41,7 @@ composable, so you can pick and choose what you need.
     icon="video"
     href="/protocols/streaming"
   >
-    Build low-latency peer-to-peer audio and video streaming applications.
+    Build low-latency audio and video streaming applications.
   </Card>
   <Card
     title="API documentation"
diff --git a/protocols/automerge.mdx b/protocols/automerge.mdx
@@ -10,8 +10,8 @@ eventually converging to the same state on every replica.
 
 ## Example
 
-This example highlights how to integrate [automerge's sync protocol](https://automerge.org/docs/hello/) with
-[iroh's peer-to-peer connectivity](/concepts/discovery).
+This example highlights how to integrate [automerge's local-first CRDT](https://automerge.org/docs/hello/) with
+[iroh's connectivity](/concepts/discovery).
 
 
 ```bash
@@ -31,7 +31,7 @@ Endpoint Id: lkpz2uw6jf7qahl7oo6qc46qad5ysszhtdzqyotkb3pwtd7sv3va
 
 You can exchange this public key with anyone to establish a secure, encrypted
 connection anywhere.  In most cases this connection is even automatically
-upgraded to a direct peer-to-peer connection.
+upgraded to a direct connection.
 
 Now, let's start another endpoint in the second terminal that will connect to the
 first endpoint:
@@ -95,4 +95,4 @@ that round.
 ## Learn more
 - [iroh-automerge example source code on Github](https://github.com/n0-computer/iroh-examples/blob/main/iroh-automerge/src/protocol.rs)
 - [automerge's sync protocol](https://docs.rs/automerge/latest/automerge/sync/)
-- [iroh's peer-to-peer connectivity](https://docs.rs/iroh/latest/iroh/net/index.html)
+- [iroh docs](https://docs.rs/iroh/latest/iroh/net/index.html)
diff --git a/protocols/blobs.mdx b/protocols/blobs.mdx
@@ -24,7 +24,7 @@ cargo add iroh-blobs
 
 ## Tutorial
 
-Let's dive into iroh by building a simple peer-to-peer file transfer tool in rust! 
+Let's dive into iroh by building a simple file transfer tool in rust! 
 
 At the end we should be able to transfer a file from one device by running this:
 
@@ -288,7 +288,7 @@ endpoint.close().await;
 
 ## That's it!
 
-You've now successfully built a small tool for peer-to-peer file transfers! 🎉
+You've now successfully built a small tool for file transfers! 🎉
 
 The full example with the very latest version of iroh and iroh-blobs can be [viewed on github](https://github.com/n0-computer/iroh-blobs/blob/main/examples/transfer.rs).
 
diff --git a/protocols/using-quic.md b/protocols/using-quic.md
@@ -4,7 +4,7 @@ title: "Using QUIC"
 
 ## Why this matters for iroh
 
-iroh is built on top of QUIC, providing peer-to-peer connectivity, NAT traversal, and encrypted connections out of the box. While iroh handles the hard parts of networking—holepunching, relay servers, and discovery—**you still need to design how your application exchanges data once connected**.
+iroh is built on top of QUIC, providing connectivity, NAT traversal, and encrypted connections out of the box. While iroh handles the hard parts of networking—holepunching, relay servers, and discovery—**you still need to design how your application exchanges data once connected**.
 
 Many developers reach for iroh expecting it to completely abstract away the underlying transport. However, iroh intentionally exposes QUIC's powerful stream API because:
 
diff --git a/protocols/writing-a-protocol.mdx b/protocols/writing-a-protocol.mdx
@@ -15,7 +15,7 @@ The protocol itself works like this:
 
 ## Listening for connections
 
-As established in the [router] and [protocol] pages, you'll first need to decide on an "Application-Layer Protocol Negotiation" (ALPN) string.
+As established in the [protocol] page, you'll first need to decide on an "Application-Layer Protocol Negotiation" (ALPN) string.
 We'll use "iroh-example/echo/0":
 
 ```rs
diff --git a/what-is-iroh.mdx b/what-is-iroh.mdx
@@ -2,30 +2,35 @@
 title: "What is iroh?"
 ---
 
-iroh is a modular peer-to-peer networking stack written in Rust. It provides
-the building blocks to create decentralized applications that can communicate
-securely and efficiently over the internet.
+iroh is a modular networking stack written in Rust. It provides
+the building blocks to create applications that can communicate
+using fast, cheap, and reliable connections.
 
 ## Core features
-- **Peer-to-peer connectivity**: iroh enables direct connections between
+- **Fast**: iroh enables direct connections between
   devices, allowing them to communicate without relying on centralized servers.
-  It uses relay servers as a fallback when direct connections are not possible.
-- **Secure communication**: All connections established through iroh are
-  authenticated and encrypted end-to-end using the QUIC protocol, ensuring data
-  privacy and integrity.
-- **Modular protocols**: iroh is built around a system of composable protocols
+- **Reliable**: iroh is designed to work in challenging network conditions.  It
+uses relay servers as a fallback when direct connections are not possible.
+- **Secure**: All connections established through iroh are authenticated and
+encrypted end-to-end using the QUIC protocol, ensuring data privacy and
+integrity.
+- **Modular**: iroh is built around a system of composable protocols
   that can be mixed and matched to suit the needs of different applications. This
   allows developers to easily add functionality such as file sharing, messaging,
   and real-time collaboration.
 
 ## Use cases
-- **Decentralized applications**: iroh provides the networking foundation for
-  building decentralized applications that can operate without central servers.
-- **File sharing**: With protocols like iroh-blobs, iroh enables efficient
-  peer-to-peer file sharing.
-- **Real-time collaboration**: iroh's support for flexible data protocols allows
+- **Local-first, offline-first, peer-to-peer applications**: iroh provides the networking foundation for
+  building applications that can operate without reliance on servers.
+- **Files & blobs**: With protocols like [iroh-blobs](/protocols/blobs), iroh enables efficient
+  file transfer.
+- **Structured data**: iroh's support for flexible data protocols like [KV
+CRDTs](/protocols/kv-crdts) and [Automerge](/protocols/automerge) allows
 developers to build applications that support real-time collaborative editing
 and data synchronization. Any kind of CRDT or OT sync protocol can be integrated.
+- **Real-time communication**: Build [chat applications](/examples/chat), [RPC
+services](/protocols/rpc), and [streaming data](/protocols/streaming) with
+iroh's communication protocols.
 
 ## Getting started
 To get started with iroh, check out the [quickstart guide](/quickstart) or explore the

Original file line number	Diff line number	Diff line change
`@@ -21,6 +21,7 @@`
`21`	`21`	`"examples/examples",`
`22`	`22`	`{`
`23`	`23`	`"group": "How it works",`
	`24`	`+ "expanded": true,`
`24`	`25`	`"pages": [`
`25`	`26`	`"concepts/endpoints",`
`26`	`27`	`"concepts/tickets",`
`@@ -43,7 +44,7 @@`
`43`	`44`	`]`
`44`	`45`	`},`
`45`	`46`	`{`
`46`		`- "group": "Communicating over Iroh",`
	`47`	`+ "group": "Building your App",`
`47`	`48`	`"pages": [`
`48`	`49`	`"protocols/kv-crdts",`
`49`	`50`	`"protocols/blobs",`