Resolve TODOs in README

README.md

@@ -14,7 +14,7 @@ TFW consists of 3 repositories:
 
 See the documentation of each in their `README.md` files.
 
-To learn the stuff you need to know about TFW in order to get started you should consult the `baseimage-tutorial-framework` repo first.
+To learn the stuff you need to know about TFW in order to get started you should consult the [baseimage-tutorial-framework](https://github.com/avatao-content/baseimage-tutorial-framework) repo first.
 
 Getting started with creating challenges using the framework – *setting up a development environment, building, running and such* – is documented here.
 
@@ -26,7 +26,7 @@ Just copy and paste the following command in a terminal:
 
 > You have trust issues regarding the public key infrastructure? You can request a checksum authenticated version of the installer command from our team!
 
-This will set up a dev environment based on `test-tutorial-framework` just for you:
+This will set up a dev environment based on [test-tutorial-framework](https://github.com/avatao-content/test-tutorial-framework) just for you:
 - it builds the latest release of the framework Docker baseimage locally
 - it pins `solvable/Dockerfile` to use the this image
 - it includes the latest frontend in `solvable/frontend` with dependencies installed
@@ -41,7 +41,7 @@ It is advisable to run the frontend locally while developing to avoid really loo
 
 ### Doing it manually
 
-In case you **must** do it for some reason you can build & run manually.
+In case you **must** *really* do it then you can build & run manually.
 Note that this is relatively painful and you should use the `hack/tfw.sh` script when possible.
 
 Building without frontend – execute from project root:
@@ -50,7 +50,7 @@ Building without frontend – execute from project root:
 
 This will create a Docker image without the frontend, which you can run locally. For procudtion builds exclude the argument `--build-arg NOFRONTEND=1` to include a frontend instance.
 
-Running – execute:
+Execute the following command to run the image:
 
 `docker run --rm -p 8888:8888 -e AVATAO_SECRET=secret test-tutorial-framework` 
 
@@ -92,10 +92,10 @@ solvable
 └── 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.
+Note that our baseimage *requires* the `nginx`, `supervisor` and `frontend` folders to be in these **exact** locations and to be 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 your version anywhere, just be sure to adjust your `Dockerfile` accordingly.
-It contains a simple example of using TFW.
+The `src` directory contains a simple example of using TFW
 
 ### nginx
 
@@ -103,7 +103,7 @@ All TFW based challenges expose a single port defined in the `TFW_PUBLIC_PORT` e
 This means that in order to listen on more than a single port we must use a reverse proxy.
 
 Any `.conf` files in `solvable/nginx/` will be automatically included in the nginx configuration.
-In case you want serve a website or service you must proxy it through `TFW_PUBLIC_PORT`.
+In case you want to serve a website or service you must proxy it through `TFW_PUBLIC_PORT`.
 This is really easy: just create a config file in `solvable/nginx/` similar to this one:
 ```text
 location /yoururl {
@@ -117,10 +117,10 @@ You can learn about configuring nginx in [this](https://www.digitalocean.com/com
 ### supervisor
 
 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.
+When working with TFW you can run as many processes as you want to by using supervisord.
 
 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.
+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 your configuration file.
 
 To run your own webservice for instance you need to create a config file in `solvable/supervisor/` similar to this one:
@@ -143,9 +143,8 @@ This is a clone of the `frontend-tutorial-framework` repository with dependencie
 
 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**
+If all you want to do is starting a simple web application and to send some messages you can mostly skip the Angluar knowledge bit.
+Refer to the example in this repo.
 
 ### src
 
@@ -168,19 +167,24 @@ As you can see this file is set up to start with the container in `solvable/supe
 As you can see they run in a separate process (set up in `solvable/supervisor/event_handlers.conf`).
 These event handlers could be implemented in any language that has ZMQ bindings.
 
+Note that you don't have to use all our event handlers.
+Should you want to avoid using a feature, you can just delete the appropriate event handler from `event_handler_main.py`.
+
+It is genarally a good idea to separate these files from the rest of the stuff in `solvable`, so it is a good practice to create an `src` directory.
+
 ## Baby steps
 
-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
+When creating your own challenge the process should be the following:
+1. Use our install script to bootstrap your dev environment
+2. Create an FSM that describes your challenge
     - 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`
-4. Creating event handlers connecting to the `TFWServer` handling events you want to handle:
-    - Creating an event handler server: `solvable/src/event_handler_main.py`
-    - Setting it up to run: `solvable/supervisor/event_handlers.conf`
-5. Modifying the frontend in `solvable/frontend` to fit your challenge
+3. Create a `TFWServer` instance and set it up to run:
+    - Create a server app: `solvable/src/tfw_server.py`
+    - Set it up to run: `solvable/supervisor/tfw_server.conf`
+4. Create event handlers connecting to the `TFWServer` handling events you want to process:
+    - Create an event handler server: `solvable/src/event_handler_main.py`
+    - Set it up to run: `solvable/supervisor/event_handlers.conf`
+5. Modify 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 written in step 4