diff --git a/docs/apache-airflow/core-concepts/overview.rst b/docs/apache-airflow/core-concepts/overview.rst
index 9ee9ea8b0b1859..c49de8d17cda89 100644
--- a/docs/apache-airflow/core-concepts/overview.rst
+++ b/docs/apache-airflow/core-concepts/overview.rst
@@ -181,6 +181,14 @@ executed in the context of the scheduler.
 
 .. image:: ../img/diagram_dag_processor_airflow_architecture.png
 
+.. note::
+
+    When DAG file is changed there can be cases where the scheduler and the worker will see different
+    versions of the DAG until both components catch up. You can avoid the issue by making sure dag is
+    deactivated during deployment and reactivate once finished. If needed, the cadence of sync and scan
+    of DAG folder can be configured. Please make sure you really know what you are doing if you change
+    the configurations.
+
 .. _overview:workloads:
 
 Workloads