Order instructions chronologically.

Author: RubenVerborgh

api-websockets.md

@@ -8,20 +8,20 @@ versioned as a whole.
 This is a _draft_ protocol.
 This specific version is identified by the string `solid-ws-draft/v0.1.0-alpha`.
 
-## Subscribing
+## Protocol description
 
 Live updates are currently only supported through WebSockets. This describes a
 subscription mechanism through which clients can be notified in real time of
 changes affecting a given resource.
 
-The PubSub system is very basic. Clients only need to open a WebSocket
-connection and *sub*(scribe) to a given resource URI. If any change occurs in
-that resource, a *pub*(lish) event will be sent to all the subscribed clients.
-
-The WebSocket server URI is the same for any resource located on a given data
-space (same hostname). To discover the URI of the WebSocket server, clients can
-send an HTTP OPTIONS request. The server will then include an `Updates-Via` header in
-the response:
+### Discovery
+The PubSub system is very basic.
+First, a client needs to obtain the URI of the WebSocket.
+The WebSocket server URI is the same for any resource
+located on a given data space (same hostname).
+To discover the URI of the WebSocket server,
+clients can send an HTTP `OPTIONS` request.
+The server will then include an `Updates-Via` header in the response:
 
 REQUEST:
 
@@ -35,9 +35,24 @@ RESPONSE:
 ```http
 HTTP/1.1 200 OK
 ...
-Updates-Via: wss://example.org/
+Updates-Via: wss://example.org
 ```
 
+### Connection
+Then, the client needs to open a WebSocket connection
+to that URI.
+
+For example, in JavaScript, this could be done as follows:
+
+```
+const socket = new WebSocket('wss://example.org');
+```
+
+### Subscription
+Then, the client needs to *sub*(scribe) to a given resource URI.
+If any change occurs in that resource,
+a *pub*(lish) event will be sent to all the subscribed clients.
+
 To subscribe to a resource, clients will need to send the keyword `sub` followed
 by an empty space and then the URI of the resource:
 
@@ -81,6 +96,7 @@ Then the following notification message will be sent:
 pub https://example.org/data/
 ```
 
+### Example
 Here is a Javascript example on how to subscribe to live updates for a `test`
 resource at `https://example.org/data/test`: