diff --git a/README.md b/README.md
index 198ee33..503967a 100644
--- a/README.md
+++ b/README.md
@@ -201,6 +201,29 @@ Should you want to avoid using a feature, you can just delete the appropriate ev
 
 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.
 
+### FSM
+
+A good state machine is the backbone of a good TFW challenge.
+
+There are two ways to define a state machine:
+    - Using a YAML configuration file
+    - Implementing it in Python by hand
+
+The first option enables you to handle FSM callbacks and custom logic in any programming language (not just Python) and is generally really easy to work with.
+You should choose this method unless you have good reason not to.
+This involves creating your YAML file (see `test_fsm.yml` for an example) and parsing it using our `YamlFSM` class (see `event_handler_main.py` for an example).
+
+The second option allows you to implement your FSM in Python, using the transitions library.
+To do this just subclass our `FSMBase` class or use our `LinearFSM` class for simple machines (see `test_fsm.py` for an example).
+
+In your FSM you can define callbacks for states and transitions.
+State callbacks:
+    - `on_enter`
+    - `on_exit`
+Transition callbacks:
+    - `before`
+    - `after`
+
 ## Baby steps
 
 When creating your own challenge the process should be the following: