Improve documentation

README.md

@@ -2,7 +2,8 @@
 
 This is the beating heart of TFW – the Docker baseimage containing the internals of the framework.
 
-All tutorial-framework challenges are child images of this one: their `Dockerfile`s all begin with `FROM avatao/tutorial-framework`.
+Every tutorial-framework based challenge has a `solvable` Docker image based on this one: their `Dockerfile`s begin with `FROM eu.gcr.io/avatao-challengestore/tutorial-framework`.
+Note that TFW is not avaliable on Docker Hub due to legal reasons and is only accessible through local builds (dont't worry, we've got you covered with build scripts in the `test-tutorial-framework` repo).
 
 This document explains the general concepts of TFW and should be the first thing you read before getting started with development.
 
@@ -12,24 +13,25 @@ For more on building and running you should consult the `test-tutorial-framework
 
 The goal of the tutorial-framework is to help content developers in creating interactive tutorials for the Avatao platform.
 
-To make this possible TFW implements a robust messaging system and provides several pre-written components built upon it, such as a file editor or a terminal (running in your browser).
+To make this possible TFW implements a robust messaging system and provides several pre-written components built upon it, such as a file editor and a terminal (both running in your browser).
 
 The foundation of the whole framework is the messaging system connecting the frontend with the backend.
-Frontend components use websockets to connect to TFW, to which you can hook several *event handlers* defining how to handle specific messages.
+Frontend components use websockets to connect to the TFW server, to which you can hook several *event handlers* defining how to handle specific messages.
 
 ![TFW architecture](docs/tfw_architecture.png)
 
 ### Event handlers
 
-Imagine event handlers as callbacks that are executed when TFW receives a specific type of message. For example you could send a message to the framework when the user does something of note.
+Imagine event handlers as callbacks that are invoked when TFW receives a specific type of message. For instance you could send a message to the framework when the user does something of note.
 
 This allows you to define actions triggered on the backend when the user presses a button on the frontend, moves the cursor to a specific area or anything like that.
 
-Event handlers use ZeroMQ to connect to the framework. They are as loosely-coupled as possible: usually they are running in separate processes and only communicate with TFW through ZMQ.
+Event handlers use ZeroMQ to connect to the framework. Due to this they are as loosely-coupled as possible: usually they are running in separate processes and only communicate with TFW through ZMQ.
 
-Most of pre-made event handlers are writen in Python3, but you can write event handlers in any language that has ZeroMQ bindings (this means virtually any language).
+Our pre-made event handlers are written in Python3, but you can write event handlers in any language that has ZeroMQ bindings (this means virtually any language).
 
 This makes the framework really flexible: you can demonstrate the concepts you want to in any language while using the same set of tools provided by TFW.
+Inside Avatao this means that any of the content teams can use the framework with ease.
 
 ### FSM
 
@@ -38,7 +40,7 @@ This allows you to track users progressing with the tasks you've defined for the
 
 For instance you could represent whether the user managed to create a malicious user with a state called `user_registered` and subscribe callbacks to events regarding that state (like entering or leaving).
 
-You could create challenges that can be completed in several different ways: imagine a state called `challenge_complete`, which represents when the challenge is completed. Several series of actions could lead to this state.
+You could create challenges that can be completed in several different ways: imagine a state called `challenge_complete`, which represents when the challenge is completed. Several series of actions (triggers) could lead to this state.
 
 This enables you to guide your users through the experience you've envisioned with your tutorial.
 We can provide a whole new level of interactivity in our challenges because we know what the user is doing.