Additional documentation to explain discontinuity event behaviour

Author: lukewhiting

docs/reference/watcher/trigger/schedule.asciidoc

@@ -13,6 +13,31 @@ in the schedule.
 are triggered when expected, you should synchronize the clocks of all nodes in the
 cluster using a time service such as http://www.ntp.org/[NTP].
 
+When specifying a timezone for a watch, keep in mind the effect daylight savings time
+transitions may have on the schedule, especially if the watch is scheduled to run
+during the transition. Here's how {watcher} handles watches scheduled during discontinuities:
+
+==== Gap Transitions
+These occur when the clock moves forward, such as when daylight savings time starts
+and cause certain hours or minutes to be skipped. If your watch is scheduled to run
+during a gap transition, the watch is executed at the same time as before the transition.
+
+Example: If a watch is scheduled to run daily at 1:30AM in the `Europe/London` time zone and
+the clock moves forward one hour from 1:00AM (GMT+0) to 2:00AM (GMT+1), the watch is executed
+at 2:30AM (GMT+1) which would have been 1:30AM before the transition. Subsequent executions
+happen at 1:30AM (GMT+1).
+
+==== Overlap Transitions
+These occur when the clock moves backward, such as when daylight savings time ends
+and cause certain hours or minutes to be repeated. If your watch is scheduled to run
+during an overlap transition, only the first occurrence of the time causes to the watch
+to execute with the second being skipped.
+
+Example: If a watch is scheduled to run at 1:30 AM and the clock moves backward one hour
+from 2:00AM to 1:00AM, the watch is executed at 1:30AM and the second occurrence after the
+change is skipped.
+
+=== Throttling
 Keep in mind that the throttle period can affect when a watch is actually executed.
 The default throttle period is five seconds (5000 ms). If you configure a schedule
 that's more frequent than the throttle period, the throttle period overrides the
@@ -21,6 +46,7 @@ and set the schedule to every 10 seconds, the watch is executed no more than
 once per minute. For more information about throttling, see
 <<actions-ack-throttle>>.
 
+=== Schedule Types
 {watcher} provides several types of schedule triggers:
 
 * <<schedule-hourly, `hourly`>>