polishing of monitor analysis

Rewritten-docs.md

@@ -288,8 +288,8 @@ addons (mostly administrative features).
   supervisor
 - _solution resubmission_ -- teachers should be able edit student's solutions
   and privately resubmit them, optionally saving all results (including
-  temporary ones); this feature can be used to quickly fix errors in the
+  temporary ones); this feature can be used to quickly fix obvious errors in the
-  solution 
+  solution and see if it is otherwise viable
 - _localization_ -- all texts (UI and exercises) should be translatable
 - _formatted exercise texts_ -- Markdown or another lightweight markup language
   should be supported for formatting exercise texts
@@ -958,10 +958,6 @@ rules out ZeroMQ -- while it is very useful for asynchronous communication
 between backend components, it is practically impossible to use it from a web
 browser. There are several other options:
 
-- *TCP sockets* -- TCP sockets give a reliable means of a full-duplex
-  communication. All major operating systems support this protocol and there are
-  libraries which simplify the implementation.  On the other side, it is not
-  possible to initiate a TCP socket from a web browser.
 - *WebSockets* -- The WebSocket standard is built on top of TCP. It enables a
   web browser to connect to a server over a TCP socket. WebSockets are
   implemented in recent versions of all modern web browsers and there are
@@ -1401,26 +1397,33 @@ development.
 
 Users want to view real time evaluation progress of their solution. It can be
 easily done with established double-sided connection stream, but it is hard to
-achieve with web technologies. HTTP protocol works differently on separate
+achieve with plain HTTP. HTTP itself works on a separate request basis with no
-requests basis with no long term connection. However, there is widely used
+long term connection. The HTML5 specification contains Server-Sent Events - a
-technology to solve this problem, WebSocket protocol.
+means of sending text messages unidirectionally from an HTTP server to a
-
+subscribed website. Sadly, it is not supported in Internet Explorer and Edge.
-Working with WebSocket protocol from the backend is possible, but not ideal from
+
-design point of view. Backend should be hidden from public internet to minimize
+However, there is another widely used technology that can solve this problem --
-surface for possible attacks. With this in mind, there are two possible options:
+the WebSocket protocol. It is more general than necessary (it enables
-
+bidirectional communication) and requires additional web server configuration,
-- send progress messages through API
+but it is supported in recent versions of all major web browsers.
-- make separate component for progress messages
+
-
+Working with the WebSocket protocol from the backend is possible, but not ideal
-Each of the two possibilities has some pros and cons. The first one is good
+from the design point of view. Backend should be hidden from public internet to
-because there is no additional component and API is already publicly visible. On
+minimize surface for possible attacks. With this in mind, there are two possible
-the other side, working with WebSocket protocol from PHP is not much pleasant
+options:
-(but it is possible) and embedding this functionality into API is not
+
-extendable. The second approach is better for future changing the protocol or
+- send progress messages through the API
-implementing extensions like caching of messages. Also, the progress feature is
+- make a separate component that forwards progress messages to clients
-considered only optional, because there may be clients for which this feature is
+
-useless. Major drawback of separate component is another part, which needs to
+Both of the two possibilities have their benefits and drawbacks. The first one
-be publicly exposed.
+requires no additional component and the API is already publicly visible. On the
+other side, working with WebSockets from PHP is complicated (but it is possible
+with the help of third-party libraries) and embedding this functionality into
+API is not extendable. The second approach is better for future changing the
+protocol or implementing extensions like caching of messages. Also, the progress
+feature is considered only optional, because there may be clients for which this
+feature is useless. Major drawback of separate component is another part, which
+needs to be publicly exposed.
 
 We decided to make a separate component, mainly because it is smaller component
 with only one role, better maintainability and optional demands for progress