1 files changed, 35 insertions, 10 deletions
diff --git a/docs/en/cowboy/2.0/guide/ws_protocol/index.html b/docs/en/cowboy/2.0/guide/ws_protocol/index.html
index 70a3adfe..5a640c49 100644
--- a/docs/en/cowboy/2.0/guide/ws_protocol/index.html
+++ b/docs/en/cowboy/2.0/guide/ws_protocol/index.html
@@ -78,12 +78,12 @@ a vital component of soft realtime Web applications.</p></div>
 connections between the client, typically a Web browser,
 and the server. It uses the HTTP Upgrade mechanism to
 establish the connection.</p></div>
-<div class="paragraph"><p>Websocket connections are asynchronous, unlike HTTP. This
-means that not only can the client send frames to the server
-at any time, but the server can also send frames to the client
-without the client initiating anything other than the
-Websocket connection itself. This allows the server to push
-data to the client directly.</p></div>
+<div class="paragraph"><p>Websocket connections are fully asynchronous, unlike
+HTTP/1.1 (synchronous) and HTTP/2 (asynchronous, but the
+server can only initiate streams in response to requests).
+With Websocket, the client and the server can both send
+frames at any time without any restriction. It is closer
+to TCP than any of the HTTP protocols.</p></div>
 <div class="paragraph"><p>Websocket is an IETF standard. Cowboy supports the standard
 and all drafts that were previously implemented by browsers,
 excluding the initial flawed draft sometimes known as
@@ -91,6 +91,30 @@ excluding the initial flawed draft sometimes known as
 </div>
 </div>
 <div class="sect1">
+<h2 id="_websocket_vs_http_2">Websocket vs HTTP/2</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>For a few years Websocket was the only way to have a
+bidirectional asynchronous connection with the server.
+This changed when HTTP/2 was introduced. While HTTP/2
+requires the client to first perform a request before
+the server can push data, this is only a minor restriction
+as the client can do so just as it connects.</p></div>
+<div class="paragraph"><p>Websocket was designed as a kind-of-TCP channel to a
+server. It only defines the framing and connection
+management and lets the developer implement a protocol
+on top of it. For example you could implement IRC over
+Websocket and use a Javascript IRC client to speak to
+the server.</p></div>
+<div class="paragraph"><p>HTTP/2 on the other hand is just an improvement over
+the HTTP/1.1 connection and request/response mechanism.
+It has the same semantics as HTTP/1.1.</p></div>
+<div class="paragraph"><p>If all you need is to access an HTTP API, then HTTP/2
+should be your first choice. On the other hand, if what
+you need is a different protocol, then you can use
+Websocket to implement it.</p></div>
+</div>
+</div>
+<div class="sect1">
 <h2 id="_implementation">Implementation</h2>
 <div class="sectionbody">
 <div class="paragraph"><p>Cowboy implements Websocket as a protocol upgrade. Once the
@@ -103,10 +127,11 @@ the Autobahn test suite, which is an extensive suite of tests
 covering all aspects of the protocol. Cowboy passes the
 suite with 100% success, including all optional tests.</p></div>
 <div class="paragraph"><p>Cowboy&#8217;s Websocket implementation also includes the
-x-webkit-deflate-frame compression draft which is being used
-by some browsers to reduce the size of data being transmitted.
-Cowboy will automatically use compression as long as the
-<code>compress</code> protocol option is set when starting the listener.</p></div>
+permessage-deflate and x-webkit-deflate-frame compression
+extensions.</p></div>
+<div class="paragraph"><p>Cowboy will automatically use compression as long as the
+<code>websocket_compress</code> protocol option is set when starting
+the listener.</p></div>
 </div>
 </div>