Fix and extend docs

README.md

@@ -74,7 +74,7 @@ your_repo
 └── config.yml
 ```
 
-The only notable difference is that the `solvable` Docker image is a child image of our baseimage: `solvable/Dockerfile` begins with `FROM eu.gcr.io/avatao-challengestore/tutorial-framework`.
+The only notable difference is that the `solvable` Docker image is a child of our baseimage: `solvable/Dockerfile` begins with `FROM eu.gcr.io/avatao-challengestore/tutorial-framework`.
 
 From now on we are going to focus on the `solvable` image.
 
@@ -88,12 +88,13 @@ solvable
 ├── nginx        webserver configurations
 ├── supervisor   process manager (init replacement)
 ├── frontend     clone of the frontend-tutorial-framework repo with dependencies installed
-└── src          challenge source code
+└── src          example source code
 ```
 
 Note that our baseimage *requires* the `nginx`, `supervisor` and `frontend` folders to be in these **exact** locations, used as described below. This is a contract your image **must** comply.
 
-The `src` directory is not a concept of TFW and you can call it however you like and put it's contens anywhere, just be sure to adjust your `Dockerfile` accordingly.
+The `src` directory is not a concept of TFW and you can call it however you like and put your version anywhere, just be sure to adjust your `Dockerfile` accordingly.
+It contains a simple example of using TFW.
 
 ### nginx
 
@@ -114,12 +115,12 @@ You can learn about configuring nginx in [this](https://www.digitalocean.com/com
 
 ### supervisor
 
-In most Docker conainers there is a single running process with `PID 1`.
+In most Docker conainers there is a single process running (it gets `PID 1`).
 Using TFW you can run as many processes as you want to using supervisord.
 
-Any `.conf` files in the `solvable/supervisor/` will be included in the supervisor configuration.
+Any `.conf` files in the `solvable/supervisor/` directory will be included in the supervisor configuration.
 The programs you define this way are easy to manage (starting/stopping/restarting) using the `supervisorctl` command line tool or our built-in event handler.
-You can even configure your processes to start with the container by including `autostart=true` in the configuration file.
+You can even configure your processes to start with the container by including `autostart=true` in your configuration file.
 
 To run your own webservice for instance you need to create a config file in `solvable/supervisor/` similar to this one:
 
@@ -131,7 +132,7 @@ command=python3 server.py
 autostart=true
 ```
 
-This starts the `/home/user/example/server.py` script using `python3` after your container entered the running state (because of `autostart=true`).
+This starts the `/home/user/example/server.py` script using `python3` after your container entered the running state (because of `autostart=true`, supervisor does not start programs by default).
 
 You can learn more about configuring supervisor [here](http://supervisord.org/configuration.html).
 
@@ -139,9 +140,16 @@ You can learn more about configuring supervisor [here](http://supervisord.org/co
 
 This is a clone of the `frontend-tutorial-framework` repository with dependencies installed in `solvable/frontend/node_modules`.
 
+You can modify it to fit your needs, but this requires some Angular knowledge (not much at all).
+
+If all you want to do is start a simple web application and send some messages you can mostly skip the Angluar knowledge bit. Refer to the example in this repo.
+
+**TODO: example non-angular webapp**
+
 ### src
 
-This folder contains the source code of the challenge.
+This folder contains the source code of a server running TFW and an other server running our event handlers.
+Note that this is not a part of the framework by any means, these are just simple examples.
 
 ```
 solvable/src
@@ -151,7 +159,8 @@ solvable/src
 ```
 
 The core of the framework is the `TFWServer` class, which is instanciated in `tfw_server.py`.
-This class handles the forwarding of the messages from the frontend to the event handlers connecting to it via ZMQ and manages the FSM.
+This class handles the forwarding of the messages from the frontend to the event handlers connecting to it via ZMQ.
+It also manages the FSM.
 As you can see this file is set up to start with the container in `solvable/supervisor/tfw_server.conf`.
 
 `event_handler_main.py` contains example usage of our pre-defined event handlers written in Python3.
@@ -163,7 +172,7 @@ These event handlers could be implemented in any language that has ZMQ bindings.
 When creating your own challange the process should be something like this:
 1. Using our install script to bootstrap your dev environment
 2. Creating an FSM that describes your challenge
-    - This is done in `solvable/src/test_fsm.py`
+    - An example is in `solvable/src/test_fsm.py`
 3. Creating a `TFWServer` instance and setting it up to run:
     - Creating a server app: `solvable/src/tfw_server.py`
     - Setting it up to run: `solvable/supervisor/tfw_server.conf`
@@ -173,5 +182,6 @@ When creating your own challange the process should be something like this:
 5. Modifying the frontend in `solvable/frontend` to fit your challenge
     - This usually involves using our pre-made components
     - And perhaps doing some of your own stuff, like:
-        - Sending messages then handling these in event handlers
+        - Sending messages then handling these in event handlers written in step 4
         - Sending triggers to step the FSM
+        - Including images of cats