diff --git a/docs/core/entity.md b/docs/core/entity.md
index cc33b8c3..8c74a870 100644
--- a/docs/core/entity.md
+++ b/docs/core/entity.md
@@ -119,6 +119,17 @@ The following properties are also available on entities. However, they are for a
 | state_attributes                | <code>dict &#124; None</code> | `None` | State attributes of a base domain. This property is implemented by the domain base entity and should not be implemented by integrations.
 | unit_of_measurement             | <code>str &#124; None</code> | The unit of measurement that the entity's state is expressed in. In most cases, for example for the `number` and `sensor` domains, this is implemented by the domain base entity and should not be implemented by integrations.
 
+## State attributes
+
+Entities can provide additional state attributes besides the built-in ones, to provide further details to it's state.
+This should be done by providing a dictionary with keys and values to the `extra_state_attributes` property.
+
+Providing additional state attributes comes with some rules:
+
+- If an attribute is expected, it should be in the dictionary. Attributes should not "come and go".
+- If an attribute is expected, but it's not providing a value right now, its value should be `None` and remain in the dictionary
+- If an attributes is not expected, it should not be in the dictionary. As example, only some attributes might provide additional context to the state when the entity runs with a certain configuration.
+
 ## System properties
 
 The following properties are used and controlled by Home Assistant, and should not be overridden by integrations.