ordering/discussion

README.md

@@ -11,9 +11,15 @@ Herein is everything needed to create unstoppable, zero-infrastructure P2P appli
 Welcome to the Internet of Peers
   _– Holepunch, the P2P Company_
 
-## Table of Content
+## Table of Contents
 
-### Guide
+### References
+
+* [Command-Line-Interface (CLI)](./reference/cli.md)
+* [Application-Programming-Interface (API)](./reference/api.md)
+* [Application Configuration](./reference/configuration.md)
+
+### Guides
 
 * [Getting Started](./guide/getting-started.md)
 * [Starting a Pear Desktop Project](./guide/starting-a-pear-desktop-project.md)
@@ -21,10 +27,4 @@ Welcome to the Internet of Peers
 * [Starting a Pear Terminal Project](./guide/starting-a-pear-terminal-project.md)
 * [Making a Pear Terminal Application](./guide/making-a-pear-terminal-app.md)
 * [Sharing a Pear Application](./guide/sharing-a-pear-app.md)
-* [Releasing a Pear Application](./guide/releasing-a-pear-app.md)
-
-### Reference
-
-* [Command-Line-Interface (CLI)](./reference/cli.md)
-* [Application-Programming-Interface (API)](./reference/api.md)
-* [Application Configuration](./reference/configuration.md)
+* [Marking a Release](./guide/releasing-a-pear-app.md)

guide/making-a-pear-desktop-app.md

@@ -234,17 +234,23 @@ Once connected messages can be sent between the applications.
 
 ### Discussion
 
+#### Whether two terminals or two machines, it's functionally the same
+
+Two application instances are running on the same machine, connecting over a Distributed Hash Table (DHT) via `hyperswarm`.
+
+The code could be copied to another machine and `pear dev` could be ran on two machines instead of two terminals. However [Sharing a Pear Application](./sharing-a-pear-app.md) covers sharing the application itself over the same DHT. So then instead of manually copying files between machines, `pear` can be used to generate a topic for an app (the application key) and then that app on a peer machine by passing that key to the `pear` installation on that machine. See [Sharing a Pear Application](./sharing-a-pear-app.md) for details.
+
+#### Peers joining topics versus clients joining servers
+
 In a traditional client-server setup the server is hosted at an IP address (or hostname) and a port, e.g. `http://localhost:3000`. This is what clients use to connect to the server.
 
 The code in `app.js` contains the line `swarm.join(topicBuffer, { client: true, server: true })`. Here `topicBuffer` is a 32 byte string. The creator of a chat room will generate a random byte string which acts as a room invinitation. Any peers with this invite (the topic) can use it to message all other peers with the invite. Note also that both applications behave the same way, neither is only a client and neither is only a server.
 
 Applications join and leave topics, so if the peer who created the topic/invite goes offline or even leaves the topic this has no effect on functionality.
 
-Two application instances are running on the same machine, connecting over a Distributed Hash Table (DHT) via `hyperswarm`.
+#### Frontend Frameworks
 
-The code could be copied to another machine and `pear dev` could be ran on two machines instead of two terminals. However [Sharing a Pear Application](./sharing-a-pear-app.md) covers sharing the application itself over the same DHT. So then instead of copying, `pear` can be used to generate a topic for an app (the application key) and then that app on a peer machine by passing that key to the `pear` installation on that machine.
-
-> No frameworks were used to build this application but any frontend framework can be used with Pear.
+No frameworks were used to build this application but any frontend framework can be used with Pear.
 
 ## Next
 

guide/sharing-a-pear-app.md

@@ -7,7 +7,7 @@ With Pear there are one single "release" (or "production") version of an app, an
 To share apps, stage them using `pear stage some-name`. This builds a new version of the app and puts them into the `some-name` channel.
 
 
-## Step 1. Stage
+## Step 1. Stage the app
 
 Before sharing the app, first stage it into a channel called `example` (the name can be anything)
 
@@ -15,7 +15,7 @@ Before sharing the app, first stage it into a channel called `example` (the name
 $ pear stage example
 ```
 
-## Step 2. Seed
+## Step 2. Seed the app
 
 After the app has been staged into the `example` channel, it now needs to be seeded. This is a way to signal that the app is now shared, so others can download and run it.
 
@@ -32,21 +32,36 @@ After the app has been staged into the `example` channel, it now needs to be see
 
 For now, keep this terminal open. As long as this process is running, your computer will help seed the application.
 
-## Step 3. Launch
+## Step 3. Run the app
 
-Because the app is now being seeded, it' possible for others with the key (`pear:nykm...`) to launch it.
-
-In another terminal (or on another computer), run:
+In another terminal run:
 
 ```
-$ pear launch pear:nykmkrpwgadcd8m9x5khhh43j9izj123eguzqg3ygta7yn1s379o
+$ pear run pear:nykmkrpwgadcd8m9x5khhh43j9izj123eguzqg3ygta7yn1s379o
 ```
 
-![Launching the app with pear launch](../assets/chat-app-6.png)
+![Launching the app with pear run](../assets/chat-app-6.png)
 
-This will download and open the app.
 
-> Anyone running the app also help to seed it. So if an app has a lot of users the original seeder could close down the process with no consequences to application uptime/functionality.
+Since the app is now being seeded, any one with the key (`pear:nykmk..`) can run the same app with `pear`.
+
+So now try running the same command on another machine or giving the command to a friend to run:
+
+```
+$ pear run pear:nykmkrpwgadcd8m9x5khhh43j9izj123eguzqg3ygta7yn1s379o
+```
+
+
+### Discussion
+
+#### Marking releases 
+
+#### Previewing prereleases
+
+#### Reseeding
+
+#### Lazy loading and sparse replication
+
 
 ## Next
 

guide/starting-a-pear-desktop-project.md

@@ -73,6 +73,7 @@ The initial background color will be light blue and the window will start with a
 
 See the [Configuration Documentation](../reference/configuration.md) for all configuration possibilities.
 
+
 ## Next
 
 * [Making a Pear Desktop Application](./making-a-pear-desktop-app.md)