diff --git a/yasmin_msgs/msg/State.msg b/yasmin_msgs/msg/State.msg
index 9c7f230..9356cbe 100644
--- a/yasmin_msgs/msg/State.msg
+++ b/yasmin_msgs/msg/State.msg
@@ -1,9 +1,9 @@
-int32 id
-int32 parent -1
+int32 id                                    # state ID inside a state machine
+int32 parent -1                             # ID of the parent of this state
 
-string name
-yasmin_msgs/Transition[] transitions
-string[] outcomes
+string name                                 # state name inside the state machine
+yasmin_msgs/Transition[] transitions        # transitions for this state
+string[] outcomes                           # list of outcomes of this state
 
-bool is_fsm
-int32 current_state -1
+bool is_fsm                                 # whether this state is a state machine
+int32 current_state -1                      # ID of the current state of this state if it is a state machine
diff --git a/yasmin_msgs/msg/StateMachine.msg b/yasmin_msgs/msg/StateMachine.msg
index 3834b91..0e64e99 100644
--- a/yasmin_msgs/msg/StateMachine.msg
+++ b/yasmin_msgs/msg/StateMachine.msg
@@ -1,2 +1 @@
-
-yasmin_msgs/State[] states
+yasmin_msgs/State[] states      # list of states that compose a state machine
diff --git a/yasmin_msgs/msg/Transition.msg b/yasmin_msgs/msg/Transition.msg
index 2842b49..33fe68e 100644
--- a/yasmin_msgs/msg/Transition.msg
+++ b/yasmin_msgs/msg/Transition.msg
@@ -1,3 +1,2 @@
-
-string outcome
-string state
+string outcome      # outcome, from a state, of the transition
+string state        # state (also can be an outcome of a state machine) of the transition