diff --git a/lib/cocoapods-core/specification/dsl.rb b/lib/cocoapods-core/specification/dsl.rb
index 2d4a34183..7c79bc7ea 100644
--- a/lib/cocoapods-core/specification/dsl.rb
+++ b/lib/cocoapods-core/specification/dsl.rb
@@ -1289,7 +1289,10 @@ def dependency(*args)
       #   variables that are set during compilation.
       #
       #   A Pod can provide multiple script phases to execute and they will be added in the order they were
-      #   declared.
+      #   declared and after taking into consideration their execution position setting.
+      #
+      #   **Note** In order to provide visibility and awareness of the contents of all script phases,
+      #   a warning will be presented to the user upon installing your pod if it includes any script phases.
       #
       #   @example
       #