Update docs

API-reference.md

@@ -1 +1,2 @@
-In this section you can find the currently available commands to manipulate the framework through the messaging system. They contain a short description about the purpose of the command, the list of subscribed event handlers, their intent and scope and any additional parameters, and finally a working example.
+In this section you can find the currently available commands to manipulate the framework through the messaging system.
+Each page contains a short description about the purpose of the command, the list of subscribed event handlers, any additional parameters, and finally a working example.

Chat-bot.md

@@ -1,4 +1,6 @@
-You can simulate a one-sided dialogue with this component. It's main purpose is to introduce the story of the exercise and the directives of each step in order to solve it, and to help the user with context-dependent hints when he/she seems to struggle to overcome a difficulty. To narrate events in a more natural speaking pace, you can queue messages and let the framework type it out according to the currently set *WPM*.
+You can simulate a one-sided dialogue with this component. It's main purpose is to introduce the story of the exercise and the directives of each step in order to solve the tutorial.
+You can help users with context-dependent hints when they seem to struggle with a certain task.
+To narrate events in a more natural pace, you can also queue a list of messages and let the framework "type them" according to the currently set *WPM* (words-per-minute).
 ***
 
 **Available commands**:

Console.md

@@ -1,4 +1,4 @@
-The console is typically used for displaying log and error messages. For instance, you may run a web server, and you would like to show the users the incoming requests, then you just have to instantiate a *ProcessLogHandler* along with a *ConsoleLogsHandler*, and start your process as a supervisor task. Besides that, you can write any kind of text manually, like unit test results.
+The console is typically used for displaying (potentially live) logs and/or error messages. For instance, you may wish to run a web server, and you would like to display all incoming requests in real time. You could just instantiate a *ProcessLogHandler* along with a *ConsoleLogsHandler* in `event_handler_main`, and start your process as a supervisor program. This would instruct the framework to print the logs of your program to the console in real time (it uses inotify in the background). Besides that, you can use it to write any kind of text manually, like unit test results.
 ***
 
 **Available commands**:

Creating-a-TFW-exercise.md

@@ -1,9 +1,9 @@
-First of all, make sure that you have every [dependency](https://github.com/avatao-content/baseimage-tutorial-framework/wiki/Setting-up-a-development-environment) installed. However, if you believe that you are ready to finally get started, here are our recommended steps:
-1. Clone the [test-tutorial-framework](https://github.com/avatao-content/test-tutorial-framework) repository, take a closer look at it contents, then attempt to [run](https://github.com/avatao-content/baseimage-tutorial-framework/wiki/tfw.sh-script) it.
-2. Try to replace the web service first with your own. If you don't need it, or you wish to run something else, just delete the `solvable/src/webservice` directory and copy your code somewhere in its parents directory. You also have to modify the supervisor configuration to fit your needs: `solvable/supervisor/webservice.conf`. It's important for your server to behave well behind a reverse proxy, requests will be sent to `/webservice/your_endpoint`.
-3. Let's fix that `frontend_config.yaml` to suit your needs. Rewrite the `iframeUrl` property to an empty string if you don't need it, compose the layouts, etc.
-4. There must be a couple of unused event handlers in the `event_handler_main.py`, you should just delete their instantiation and import, then rewrite the init parameters in the remaining ones where necessary.
-4. The next step is to start writing an **FSM**. You either use the Python-based *LinearFSM* and *FSMBase* classes that utilize the `transitions` module, or you just compile it into a *YAML* file like the `test_fsm.yml` example.
-5. Then you need to put the triggers after the respective checks, and formulate bot messages to guide the user in each step.
+First of all, make sure that you have every [dependency](https://github.com/avatao-content/baseimage-tutorial-framework/wiki/Setting-up-a-development-environment) installed. If you believe that you are ready to get started, here are our recommended steps:
+1. Clone the [test-tutorial-framework](https://github.com/avatao-content/test-tutorial-framework) repository and take a closer look at it contents, then attempt to [run](https://github.com/avatao-content/baseimage-tutorial-framework/wiki/tfw.sh-script) it.
+2. Try to replace the webservice with your own HTTP server. If you don't need it, or you wish to run something else, just delete the `solvable/src/webservice` directory and copy your code somewhere in its parents directory. You also have to modify it's supervisor configuration to fit your needs: `solvable/supervisor/webservice.conf`. It's important for your server to behave well behind a reverse proxy, as requests will be sent to `/webservice/your_endpoint`.
+3. Edit `frontend_config.yaml` to suit your needs. Rewrite the `iframeUrl` property to an empty string if you don't need it, compose the layouts, etc.
+4. At this point there should be a couple of unused event handlers defined in `event_handler_main.py`. You should just delete their instantiations and imports, then rewrite the constructor parameters in the remaining ones where you deem necessary.
+4. The next step is to create an **FSM**. You either use the Python-based *LinearFSM* and *FSMBase* classes that utilize the `transitions` Python module, or you just compile it into a *YAML* file like the `test_fsm.yml` example.
+5. You need to put the triggers after the respective checks, and formulate bot messages to guide the user through each step.
 6. When everything is ready, you can start to check your tutorial with the `check_format.py` script in the `challenge-toolbox` repository in order to be able to upload it to the platform.
-7. After you get zero errors, you can finally share it by creating a repository through the dashboard at https://platform.avatao.com, then push your solution to a `staging` branch and open a pull request, and then comes our part to make it available.
+7. After you no errors, you can finally share it by creating a repository through the dashboard at https://platform.avatao.com, then push your solution to a `staging` branch and open a pull request, and then comes our part to make it available.

FSM.md

@@ -1,4 +1,4 @@
-Another unique feature of the framework is the *FSM* - representing the state of your challenge. This allows you to track users progressing with the tasks you've defined for them to complete.
+Another unique feature of the framework is the *FSM* (finite state machine) - representing the state of your challenge. This allows you to track user progress with the tasks you've defined for them to complete.
 
 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).
 

Frontend-configuration.md

@@ -1,4 +1,4 @@
-The main page is designed to be configured dynamically, so you don't need to edit the frontend directly. **Most** of these changes can be applied without reloading the website, which is particularly useful when you have to change layouts or manipulate components after a state transition.
+The TFW frontend is designed to be dynamically configurable, so you never have to edit the frontend codebase directly. **Most** of these changes can be applied without reloading the page, which is particularly useful when you have to change layouts or manipulate components after a state transition.
 ***
 
 **Available commands**:

Process-management.md

@@ -1,4 +1,4 @@
-The challenge container's default command starts the supervisor daemon which manages every relevant process including the custom web service. *ProcessHandler* provides an interface to this daemon, and as a result of this, you are in control over the lifetime of the spawned processes. Moreover, you can retrieve (*ProcessLogHandler*) their outputs from `stdin` and `stdout`, respectively.
+The challenge image's default command (specified by `CMD` in the baseimage `Dockerfile`) starts the supervisor daemon which manages every relevant process in the container, including the custom web service. *ProcessHandler* provides an interface to this daemon over the TFW messaging system, and as a result, you are in control of the lifetime of spawned processes. Moreover, you can retrieve (*ProcessLogHandler*) their outputs from `stderr` and `stdout`, respectively.
 
 Regarding exercises, this means that you can easily restart your services after the user edited their source code / configuration files, etc.
 ***

Terminal.md

@@ -2,7 +2,7 @@ This is a full-fledged **xterm** terminal emulator, which runs right in your bro
 
 This event handler spawns a *bash* session and a *pseudoterminal*. It connects the master end of the pty to the emulator running in your browser and the slave end to bash. This essentially provides a fully functional terminal session for your users in the browser (a convenient alternative for an SSH session).
 
-This terminal is fully under your control: You can write to it (and thus execute commands) and read what commands were executed by the user using the API exposed by the TerminalEventHandler. This enables you to pre-type or execute commands for the user and figure out what they are doing in the terminal.
+This terminal is fully under your control: You can write to it (and thus execute commands) and read what commands were executed by the user using the API exposed by the TerminalHandler. This enables you to pre-type or execute commands for the user and figure out what they are doing in the terminal.
 ***
 
 **Available commands**:

Web-IDE.md

@@ -1,4 +1,4 @@
-For displaying and editing code, you can utilize the **Monaco Editor**, which supports a lot of languages, provides syntax highlighting, code completion, etc. When you need to validate the user's input, the *deploy button* comes handy. It triggers an event, so you can run unit tests or anything you need, after that the frontend waits for your reply indicating success or failure.
+For displaying and editing code, you can utilize our built in IDE based on the **Monaco Editor**, which supports lots of languages, provides syntax highlighting, code completion, etc. When you need to validate the user's input, the *deploy button* comes in handy. It triggers an event, so you can run unit tests or anything you need, after which the frontend waits for your response indicating success or failure.
 ***
 
 **Available commands**: