diff --git a/source/_components/alarm_control_panel.mqtt.markdown b/source/_components/alarm_control_panel.mqtt.markdown
index 4bf7c911cd7..6df023bdcf0 100644
--- a/source/_components/alarm_control_panel.mqtt.markdown
+++ b/source/_components/alarm_control_panel.mqtt.markdown
@@ -1,7 +1,7 @@
 ---
 layout: component
 title: "MQTT Alarm Control Panel"
-description: "Instructions how to integrate MQTT alarms into Home Assistant."
+description: "Instructions how to integrate MQTT capable Alarm Panels into Home Assistant."
 date: 2015-09-14 19:10
 sidebar: true
 comments: false
@@ -11,8 +11,17 @@ logo: mqtt.png
 ha_category: Alarm
 ---
 
+This platform enables the possibility to control an MQTT alarm panel. The Alarm Icon will change state after receiving a new state from `state_topic`. If these messages are published with RETAIN flag, the MQTT alarm will receive an instant state update after subscription and will start with correct state. Otherwise, the initial state will be `unknown`.
 
-This platform enables the possibility to control an MQTT alarm. The alarm will only change state after receiving the a new state from `state_topic`. If these messages are published with RETAIN flag, the MQTT alarm will receive an instant state update after subscription and will start with correct state. Otherwise, the initial state will be `unknown`.
+The component will accept the following states from your Alarm Panel (in lower case) :-
+
+- 'armed'
+- 'armed_home'
+- 'armed_away'
+- 'pending'
+- 'triggered'
+
+The component is able to control your Alarm Panel by publishing to the command_topic: when a user interacts with the screen icon on the frontend.
 
 ```yaml
 # Example configuration.yaml entry
@@ -35,8 +44,8 @@ Configuration variables:
 
 - **name** (*Optional*): The name of the alarm. Default is 'MQTT Alarm'.
 - **qos** (*Optional*): The maximum QoS level of the state topic. Default is 0. This QoS will also be used to publishing messages.
-- **payload_disarm** (*Optional*): The payload do disarm alarm. Default is "DISARM".
-- **payload_arm_home** (*Optional*): The payload to set armed-home mode. Default is "ARM_HOME".
-- **payload_arm_away** (*Optional*): The payload to set armed-away mode. Default is "ARM_AWAY".
+- **payload_disarm** (*Optional*): The payload do disarm your Alarm Panel. Default is "DISARM".
+- **payload_arm_home** (*Optional*): The payload to set armed-home mode on your Alarm Panel. Default is "ARM_HOME".
+- **payload_arm_away** (*Optional*): The payload to set armed-away mode on your Alarm Panel. Default is "ARM_AWAY".
 - **code** (*Optional*): If defined, specifies a code to enable or disable the alarm in the frontend.