diff --git a/docs/sample_communication.txt b/docs/bitcoinity/sample_communication.md
similarity index 94%
rename from docs/sample_communication.txt
rename to docs/bitcoinity/sample_communication.md
index edf5bfe..c5d2aa9 100644
--- a/docs/sample_communication.txt
+++ b/docs/bitcoinity/sample_communication.md
@@ -1,3 +1,6 @@
+### communication with wss://bitcoinity.org/webs_bridge/websocket ###
+
+```
 SEND >> {"topic":"all","event":"phx_join","payload":{},"ref":"1"}
 RECV << {"event":"phx_reply","payload":{"response":{},"status":"ok"},"ref":"1","topic":"all"}
 SEND >> {"topic":"webs:markets","event":"phx_join","payload":{},"ref":"2"}
@@ -5,11 +8,13 @@ RECV << {"event":"phx_reply","payload":{"response":{},"status":"ok"},"ref":"2","
 SEND >> {"topic":"webs:markets_kraken_USD","event":"phx_join","payload":{},"ref":"3"}
 RECV << {"event":"phx_reply","payload":{"response":{},"status":"ok"},"ref":"3","topic":"webs:markets_kraken_USD"}
 RECV << {"event":"new_msg","payload":{"data":{"currency":"USD","exchange_name":"bitfinex","last":29420.94784483}},"ref":null,"topic":"webs:markets"}
+```
 
 
 ---
 
 
+```
 SEND >> {"topic":"all","event":"phx_join","payload":{},"ref":"1"}
 RECV << {"event":"phx_reply","payload":{"response":{},"status":"ok"},"ref":"1","topic":"all"}
 SEND >> {"topic":"webs:markets","event":"phx_join","payload":{},"ref":"2"}
@@ -18,3 +23,4 @@ SEND >> {"topic":"webs:markets_kraken_USD","event":"phx_join","payload":{},"ref"
 RECV << {"event":"phx_reply","payload":{"response":{},"status":"ok"},"ref":"3","topic":"webs:markets_kraken_USD"}
 RECV << {"event":"new_msg","payload":{"data":{"connected_count":1355}},"ref":null,"topic":"webs:markets"}
 RECV << {"event":"new_msg","payload":{"data":{"currency":"EUR","exchange_name":"paymium","last":28363.44}},"ref":null,"topic":"webs:markets"}
+```
diff --git a/docs/sample_responses.json b/docs/bitcoinity/sample_responses.json
similarity index 100%
rename from docs/sample_responses.json
rename to docs/bitcoinity/sample_responses.json
diff --git a/src/bitcoinity_reader.cpp b/src/bitcoinity_reader.cpp
index 1e9c396..a5e55fa 100644
--- a/src/bitcoinity_reader.cpp
+++ b/src/bitcoinity_reader.cpp
@@ -76,6 +76,11 @@ namespace {
 		//out the websocket address and the correct sequence of messages to
 		//initiate the communication properly.
 		//https://github.com/terrablue
+		//1) {"topic":"all","event":"phx_join","payload":{},"ref":"1"}
+		//2) {"topic":"webs:markets","event":"phx_join","payload":{},"ref":"2"}
+		//3) {"topic":"webs:markets_bitfinex_USD","event":"phx_join","payload":{},"ref":"3"}
+		//See docs/bitcoinity/sample_communication.md for a real world example
+
 		{
 			ws.write(R"({"topic":"all","event":"phx_join","payload":{},"ref":"1"})");
 			auto resp = to_bitcoinity_message(ws.read());